XenApp and XenDesktop 7.16 Current Release

XenApp and XenDesktop 7.16 Current Release
Nov 28 , 20 17
XenApp and XenDeskt op 7 .16 is the latest Current Release version of XenApp and XenDesktop and this documentation
reflects features and configurations in this latest release. For documentation on previous Current Releases, see:
XenApp and XenDesktop 7.14
XenApp and XenDesktop 7.13
XenApp and XenDesktop 7.12
XenApp and XenDesktop 7.11
XenApp and XenDesktop 7.9
XenApp and XenDesktop 7.8
XenApp and XenDesktop 7.7
Earlier XenApp and XenDesktop Current Release versions
T he XenApp and XenDesktop product lifecycle strategy for Current Releases (CR) and Long Term Service Releases (LT SR) is
described in https://www.citrix.com/support/product-lifecycle/milestones/xenapp-xendesktop.html.
T he Citrix Cloud XenApp and XenDesktop offering is the XenApp and XenDesktop Service. For information, see XenApp and
XenDesktop Service.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.1
What's new
Dec 21, 20 17
About this release
T his XenApp and XenDesktop release includes new versions of the Windows Virtual Delivery Agents (VDAs) and new
versions of several XenApp and XenDesktop core components. You can:
Inst all or upgrade a XenApp or XenDeskt op Sit e
Use the ISO for this release to install or upgrade all the core components and VDAs. Installing or upgrading to the
latest version allows you to use all the latest features.
Inst all or upgrade VDAs in an exist ing Sit e
If you have a XenApp or XenDesktop 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 is often
helpful when you want to test enhancements in a non-production environment.
For 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.
XenApp and XenDesktop 7.16
T his product release includes the following new, modified, and enhanced features.
Installation of 7.16 VDAs is supported on a streamlined set of Windows OSs. T hese operating systems have improved GPU
compatibility that provides better performance and display experiences. T hese operating systems also support the indirect
display driver, which replaces the earlier Citrix WDDM driver.
Support ed versions f or 7 .16 Windows VDAs (and changes f rom previous release)
VDAs on Windows deskt op machines: You can install or upgrade to a 7.16 desktop VDA on machines running
Windows 10, minimum version 1607.
You cannot install or upgrade to a 7.16 desktop VDA on machines running Windows 10 versions 1507 and 1511,
Windows 8.1, Windows 8, or Windows 7.
VDAs on Windows Server machines : You can install or upgrade to a 7.16 server VDA on machines running Windows
Server 2016 or Windows Server 2012 R2.
You cannot install or upgrade to a 7.16 server VDA on machines running Windows Server 2012 or Windows Server 2008
R2.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.2
Server VDI: Using the Server VDI feature, you can deliver a desktop from a Windows Server 2016 operating system.
You cannot install or upgrade to a 7.16 desktop VDA using the /servervdi command-line option on machines running
Windows Server 2012 R2, Windows Server 2012, or Windows Server 2008 R2.
Recommendat ions and guidance
For machines with OSs that are no longer supported, you have several options.
Reimage the machine to a supported Windows version, and then install the new VDA.
If reimaging the machine is not an option but you want to upgrade the OS, uninstall the VDA before upgrading the OS.
Otherwise, the VDA will be in an unsupported state. T hen, install the new VDA.
If you want to continue to use machines with an OS that is no longer supported for the current VDA (noted above),
XenApp and XenDesktop 7.15 LT SR is the most current supported VDA version.
If the machine has version 7.15 LT SR installed (and you attempt to install a newer version), a message informs you
that you're using the latest supported version.
If the machine has a version earlier than 7.15 LT SR installed, a message guides you to CT X139030 for information. You
can download 7.15 LT SR VDAs from the Citrix website.
When you install a VDA, you can now choose whether to install the Citrix Universal Print Server PDF driver. In the installer's
graphical interface, select or clear a check box on the Addit ional Component s page. In the command-line interface, use
the /exclude "Citrix PDF Printer Driver" option to prevent the installation of that component.
T he VDA installers now include an analyzer that runs if a VDA installation fails. T he analyzer parses the failing MSI log,
displaying the exact error code, and suggests a CT X article if it's a known issue. T he analyzer also collects anonymous data
about the failure error code. Citrix can use this data to troubleshoot VDA installation failures. T he data is included with
other anonymous data collected by the Citrix Customer Experience Improvement Program (CEIP).
When you install a VDA on a desktop OS, you no longer specify whether to enable standard mode or HDX 3D Pro mode.
(T he VDA installer wizard no longer contains the HDX 3D Pro page, and the /enable_hdx_3d_pro command-line option is no
longer valid.) Instead, the VDA evaluates criteria and sets the mode automatically. If you need to override the automatic
mode setting, you can use a new policy setting. For details, see HDX 3D Pro.
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.
After removing XenApp 6.5 software from a worker server, you cannot install a current VDA on that server until you reimage
or upgrade it to a supported OS version.
Creation of machine catalogs containing Windows Server OS machines now includes an automatic RDS license check. Any
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.3
RDS license issues found are displayed, so that you can take the appropriate steps to prevent a gap in service. For details,
see Create machine catalogs.
Resource groups: When using MCS to create machine catalogs in Azure Resource Manager, you can now select from
existing empty resource groups. Alternatively, you can create resource groups.
On-demand provisioning: When using MCS to create machine catalogs in Azure Resource Manager, on-demand
provisioning reduces storage costs, provides faster catalog creation, and provides faster VM power operations. In earlier
releases, VMs were created in Azure during the provisioning process. With Azure on-demand provisioning, VMs are
created only when XenApp and XenDesktop initiates a power-on action, after the provisioning completes.
Environment : When creating a connection to Azure Resource Manager, the Azure environment list includes all Azure
worldwide regions supported by your subscription. For example, your list might include entries for the new tech previews
for Azure US Government and Azure Germany.
Support f or App-V 5.0 Deployment Conf igurat ion F iles in single admin met hod. Citrix App-V on the VDA now
supports the use of dynamic configuration files to customize an App-V 5.0 package using Deployment Configuration
Files, when applications are launched using the single admin management method. T his allows you to change the
package characteristics easily, for example by providing extra shortcuts and behaviors, without the need to resequence
the package. T his support adds the use of machine wide, deployment configuration files
(packagename_DeploymentConfig.xml) to applications in App-V packages managed by XenApp 7.x’s single admin
management method.
Support f or short cut s in App-V packages. Citrix App-V now supports the launching of applications from shortcuts
defined in App-V packages. T his allows different command-line arguments to be passed to the targets of the shortcuts.
Shortcuts are added in Studio in the same way as applications are added.
For more information, see App-V.
Scout collects and uploads diagnostics from auto-discovered Controllers and VDAs. Now, you can manually specify
additional XenApp and XenDesktop machines (such as StoreFront and Provisioning Services servers) from which diagnostics
are collected and uploaded. For details, see Citrix Scout.
Applicat ions Analyt ics. You can now analyze and monitor the performance of applications efficiently with the new
Application Analytics page available from the Applicat ions tab in Director. T he page provides a consolidated view of the
health and usage of all applications published on your Site. It shows metrics such as the number of instances per
application, and faults and errors associated with the published applications. T his feature requires Delivery Controller
Version 7.16 or later and VDAs Version 7.15 or later.
For more information, see the Application Analytics section in T roubleshooting Applications.
Access Monit or Service dat a using Version 4 of t he ODat a AP I. Create your customized monitoring and
reporting dashboards based on the Monitor Service data by using the OData V.4 endpoint. OData V.4 is based on
the ASP.NET Web API and supports aggregation queries and other improvements. Running aggregation queries improves
server-side performance. T he ASP.NET Web API fully supports the REST protocol, enabling Monitor Service consumers to
use the fully REST -compliant interface OData query.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.4
For more information, see the Monitor Service OData API.
Shadow Linux VDA user sessions. You can now shadow user sessions running on Linux VDA machines. Shadowing is
available for sessions on Linux VDAs Version 7.16 and later running the RHEL7.3 or Ubuntu 16.04 Linux distributions.
noVNC is used to connect and view Linux VDA sessions from Director. T his extension of the shadowing feature helps
administrators to troubleshoot issues on Linux VDAs efficiently.
For more information, see Shadow users.
Older Sit e version indicat ion. T he latest features and updates supported in an upgraded Director version are
available only if you also upgrade the Site. If your Delivery Controller is an earlier version than Director, the Director
console displays a message indicating the mismatch.
For more information, see Feature compatibility matrix.
Support f or domain local group. You can now add users from other forests into a domain local group, and then use
the domain local group for user assignment to XenApp and XenDesktop Delivery Groups. Director is now upgraded to
show the session details of such users. T his feature is useful for Citrix Service Provider administrators, to troubleshoot
users belonging to a tenant forest by using domain local groups to hold the tenant user or user group records.
For more information, see Domain local group configuration in Advanced configuration.
Access t o machine console. T he Machine Details panel in Director now provides access to consoles of machines
hosted on the XenServer hypervisor version 7.3. You can now troubleshoot issues in VDAs directly from Director. T his
feature requires Delivery Controller(s) Version 7.16 or later.
For more information, see Machine Console access in T roubleshoot machines.
Virtual Delivery Agents (VDAs) 7.16
Version 7.16 of the VDA for Server OS and the VDA for Desktop OS include the following enhancements to HDX
technologies:
Adapt ive t ransport enhancement . By default, adaptive transport is enabled (P ref erred ), and EDT is used when
possible, with fallback to T CP.
When adaptive transport is set to P ref erred , and session reliability enabled, EDT and T CP are attempted in parallel
during the initial connection, session reliability reconnection, and auto client reconnect. Doing so reduces connection
time if EDT is P ref erred , but the required underlying UDP transport is unavailable and T CP must be used.
Import ant : T he parallel feature requires the Citrix Receiver for Windows minimum version 4.10 or Citrix Receiver for Mac
minimum version 12.8.
Browser cont ent redirect ion. Redirects the contents of a web browser to a client device, and creates a
corresponding browser embedded within Citrix Receiver. T his feature offloads network usage, page processing, and
graphics rendering to the endpoint. Doing so improves the user experience when browsing demanding webpages,
especially webpages that incorporate HT ML5 or Flash video.
Expanded t ablet mode in Windows 10 using Windows Cont inuum. For touch enabled Windows and iOS client
devices, Windows 10 VDA starts in tablet mode when there is no keyboard or mouse attached. It starts in desktop mode
when either a keyboard or a mouse or both are attached. Detaching or attaching the keyboard on any client device or
the screen on a 2-in-1 device like a Surface Pro toggles among tablet and desktop modes. For more information, see
T ablet mode for touch screen devices using Windows Continuum in the HDX article.
HDX Insight improvement . 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. T his
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.5
release incorporates an uncompressed HDX Insight virtual channel (NSAP) exclusively dedicated to sending data points.
T he NetScaler device between the server and the most recent version of Citrix Receiver for Windows or Mac extracts
the data points. T he device then forwards the data to the HDX Insight tool. For more information, see HDX Insight in
the HDX article.
High def init ion webcam st reaming. T he applications on the server can use the high definition webcams on the client.
When a session starts, the client sends the webcam information to the server. You choose the webcam from the
application. When the webcam and the application support high definition rendering, the application uses high definition
resolution. For more information see, High definition webcam streaming in the HDX article.
Support f or use of H.265 video encoding mode. T he VDA and the most recent version of Citrix Receiver for
Windows support the use of the H.265 video codec for hardware acceleration of remote graphics and videos. T o
function, this feature must be enabled on Citrix Receiver for Windows and supported on the VDA. If the GPU at the
endpoint does not support H.265 decoding using the DXVA interface, the Citrix Receiver for Windows H.265 Decoding
f or graphics policy setting is ignored and the session falls back to using the H.264 video codec. For more information,
see Support for H.265 video encoder mode in the Citrix Receiver for Windows 4.10 documentation.
Import ant : T his support for H.265 video encoding requires a XenDesktop Platinum license.
Unicode keyboard mapping. Using a registry setting, users can avoid keyboard synchronization issues on nonWindows Citrix Receivers. Users connect to the VDA and use the local keyboard layout. Without the registry setting, if a
user changes the local and the server keyboard layouts, the keyboards might not be in sync and character output is
wrong. For more information see, Unicode keyboard mapping in the HDX article.
Also, see the install and upgrade changes described in the previous section, XenApp and XenDesktop 7.16.
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. T he default (7.9 (or newer ...)) remains the current functional level. For information, see VDA versions and
functional levels.
Citrix Licensing 11.14
Citrix Licensing 11.14 contains new features and fixed and known issues.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.6
Fixed issues
Nov 28 , 20 17
T he following issues have been fixed since Version 7.15:
AppDNA
App-V
T he parameter AppVApplications of the object returned by Get-AppLibAppVPackage is a blank array, even though
applications exist for that package and can be retrieved using Get-AppLibAppVApplication cmdlet. (After fixing, GetAppLibAppVPackage returns a populated array of AppVApplications if you call it with -RetrieveApplicationData $true.
[#DNA-23524]
Metadata support has been corrected for the following objects in the Delivery Controller SDK API snap-in
Citrix.AppLibrary.Admin.V1:
AppLibIsolationGroup
AppLibAppVApplication
AppLibLibrary
AppLibAppVPackage [#DNA-27233, #DNA-27234, #DNA-27236, #DNA-27237, #DNA-27457, #DNA-27462]
In Studio, when deleting one or more App-V applications from the Applications node, or from a selected Delivery Group,
the message "An unknown error occurred" appears. You can safely ignore the message; the applications are deleted.
[#DNA-29702]
When the cmdlet Get-ApplibAppVApplicationInfo is executed a Permission Denied error is raised. [#DNA-46589]
Citrix Director
When you open the Director Console and search for users for the first time, the loading bar does not appear. In
subsequent searches, the bar appears as expected. [#LC8190]
When you navigate to F ilt ers > Sessions in Citrix Director and attempt to resize the browser, the entire table might be
incorrectly aligned. [#LC8624]
Citrix Policy
Attempts to add a new USB redirection rule to a user policy in Active Directory might fail. T he issue occurs when the
scroll bar is not available. [#LC8112]
When attempting to manage the "Printer Assignments" policy, the following issues might occur:
T he exception "InvalidCastException" occurs when adding or editing the printer assignments policy.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.7
T he exception "InvalidOperationException" occurs when adding a new session printer.
Attempts to remove a session printer from the printer assignment policy fails. T his issue occurs when the "Remove"
option is disabled.
When you stop typing in the search box of the "Printer Assignment" policy, the search action does not start.
T he session printer override setting checkboxes (PrintQuality, PaperSize, Scale, and T rueT ypeOption) are always
selected even though you have cleared them in previously.
[#LC8146]
Citrix Studio
When you attempt to add user-assigned machines to a Delivery Group, unassigned machines might be displayed on the
"Machine allocation" page. [#LC6755]
When you attempt to add an application from the Linux VDA manually, the following error message might appear:
"Value cannot be null while publishing the application."
However, the application is added successfully when you click "OK" in the error message that appears. [#LC7910]
Attempts to access machine catalogs in Citrix Studio can cause Citrix Studio to exit unexpectedly and the following
exception occurs:
"Error Id: XDDS:ABB14FD9" [#LC7961]
T he text for the "Use storage local to the hypervisor" option in the "Add Connection and Resources" wizard that is
running on a non-English version of the Windows operating system might be truncated. [#LC8041]
After upgrading Citrix Studio to Version 7.14.1, the "Used By" column (referring to the Delivery Group that the application
is used by) for existing App-V packages might appear blank. [#LC8075]
When you click the Delivery Group hyperlink in Citrix Studio, you might not be redirected to the selected Delivery Group
node. [#LC8095]
When attempting to manage the "Printer Assignments" policy, the following issues might occur:
T he exception "InvalidCastException" occurs when adding or editing the printer assignments policy.
T he exception "InvalidOperationException" occurs when adding a new session printer.
Attempts to remove a session printer from the printer assignment policy fails. T his issue occurs when the "Remove"
option is disabled.
When you stop typing in the search box of the "Printer Assignment" policy, the search action does not start.
T he session printer override setting checkboxes (PrintQuality, PaperSize, Scale, and T rueT ypeOption) are always
selected even though you have cleared them in previously.[#LC8146]
When you select the Delivery Groups node in Citrix Studio and then select the Application tab, the hyperlink in the
Application tab might not work. [#LC8555]
Controller
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.8
When attempting to retrieve data for sessions from Citrix Director, null entries appear in the Monitor database. As a
result, certain data is not displayed in Citrix Director and the following error message appears:
"failed to retrieve data" [#LC6273]
If a Delivery Group contains one more VDAs in maintenance mode, you might not be able to select the Delivery Group to
launch published applications. [#LC6943]
After updating a machine catalog that is created using Machine Creation Services (MCS), the virtual machines hosted on
vSAN 6 or later versions might fail to start. T he following error message appears in the VMware console:
"A general system error occurred: PBM error occurred during PreProcessReconfigureSpec: pbm.fault.PBMFault; Error when
trying to run pre-provision validation; Invalid entity." [#LC7860]
When you attempt to add an application from the Linux VDA manually, the following error message might appear:
"Value cannot be null while publishing the application."
However, the application is added successfully when you click "OK" in the error message that appears. [#LC7910]
Attempts to access machine catalogs in Citrix Studio can cause Citrix Studio to exit unexpectedly and the following
exception occurs:
"Error Id: XDDS:ABB14FD9" [#LC7961]
Citrix Director might display an incorrect number of disconnected sessions at the top of every hour. [#LC8006]
T he "AllowRestart" policy for sessions on Server OS does not allow you to log off from the disconnected sessions. When
you restart a disconnected session, the session is reconnected to the previous session instead of starting a new one.
[#LC8090]
When attempting to manage the "Printer Assignments" policy, the following issues might occur:
T he exception "InvalidCastException" occurs when adding or editing the printer assignments policy.
T he exception "InvalidOperationException" occurs when adding a new session printer.
Attempts to remove a session printer from the printer assignment policy fails. T his issue occurs when the "Remove"
option is disabled.
When you stop typing in the search box of the "Printer Assignment" policy, the search action does not start.
T he session printer override setting checkboxes (PrintQuality, PaperSize, Scale, and T rueT ypeOption) are always
selected even though you have cleared them in previously.[#LC8146]
T he Monitoring Service might fail to insert new session data into the monitoring database. [#LC8191]
T he Logon Duration by User Session panel under Direct or > T rends > Logon P erf ormance might display only partial
logon records. [#LC8265]
HDX RealTime Optimization Pack
Linux VDA
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.9
Profile Management
Provisioning Services
Session Recording
StoreFront
VDA for Desktop OS
HDX 3D P ro
With HDX 3D Pro enabled on a VDA that is running on Microsoft Windows 10, a gray screen might appear intermittently
when you log on. [#LC8417]
HDX MediaSt ream F lash Redirect ion
With HDX MediaStream Flash Redirection enabled, Flash videos might fail to play on MSN.com and News.com. [#LC6823]
HDX P lug and P lay
USB devices that report the same serial number for more than one device such as Syn-Tech ProKee V2 might not get
redirected to a VDA session. T he following CDF trace appears:
"Failed to assign the instance ID, error 0xc000000d." [#LC8264]
P rint ing
Attempts to launch a published application might fail when the application is waiting for a mutex object in Citrix Print
Manager service (cpsvc.exe). [#LC6829]
T he Citrix Print Manager service (cpsvc.exe) might exit intermittently. [#LC7535]
When you roam a session between clients, session printers cannot be deleted. For example, when you configure the
policy "Printer assignments" – printer A for client A and printer B for client B, printer A might not be deleted when you
roam from client A to client B. [#LC8077]
Session/Connect ion
With local app access enabled, using the interactive logon disclaimer policy might result in a black or gray screen lasting
for 45 seconds. [#LC6518]
Attempts to reconnect to an application might fail. T he issue occurs when any of the disconnected application becomes
unresponsive when the session disconnected initially. [#LC6550]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.10
When you lock a dual-monitor session using HDX 3D Pro, only the primary monitor is locked. [#LC7767]
When you establish a Skype for Business video call, a blue window border might appear after intersecting with the
window of a third party application. [#LC7773]
With local app access enabled, using the interactive logon disclaimer policy might result in a black or gray screen.
[#LC7798]
Certain published applications might not cover the entire screen when maximized. [#LC7854]
When performing an insert operation between two Microsoft Excel 2010 worksheets running on a Version 7.9 VDA, the
Excel window might become unresponsive. [#LC7912]
In certain scenarios, seamless applications might not appear in seamless mode or certain features might not work.
[#LC8030]
With HDX 3D Pro enabled on a VDA and the policy "Message text for users attempting to log on" enabled when the
logon screen appears, attempts to launch a published desktop might fail and a gray screen appears.
To enable the fix, set the following registry key:
HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\HDX3D\BitmapRemotingConfig
Name: HKLM_DisableMontereyFBCOnInit
Value: D_WORD
Type: 1 to enable [#LC8082]
With local app access enabled, using the interactive logon disclaimer policy can cause the desktop viewer to show a gray
screen when connecting to a VDA. [#LC8136]
When you launch an application with session lingering enabled, the session might log off after the application appears.
[#LC8245]
Windows Explorer might close unexpectedly in one of the following cases:
When selecting a large number of files whose names contain more than 260 characters and then selecting the "Send
to > Fax recipient" option.
When attempting to open third-party applications.
When attempting to combine files by using Nitro PDF. [#LC8423]
Smart Cards
When you log on to a session using a smart card, the session might become unresponsive until you disconnect and
reconnect the session. [#LC8036]
Syst em Except ions
T he wfshell.exe process might exit unexpectedly, pointing to the taskbar grouping module. [#LC6968]
On systems with Hotfix Rollup Pack 7 installed, servers might experience a fatal exception, displaying a blue screen, on
picadm.sys with bugcheck code 0x00000050 (PAGE_FAULT _IN_NONPAGED_AREA). [#LC6985]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.11
Servers might experience a fatal exception, displaying a blue screen, on picadm.sys with bugcheck code 0x22. [#LC7574]
With the USB redirection policy enabled, VDAs might experience a fatal exception, displaying a blue screen with bugcheck
code SYST EM_T HREAD_EXCEPT ION_NOT _HANDLED (7e). [#LC7999]
Servers might experience a fatal exception, displaying a blue screen, on picavc.sys with bugcheck code
SYST EM_T HREAD_EXCEPT ION_NOT _HANDLED (7e). [#LC8063]
User Experience
When reconnecting to a seamless application session, the application windows might not appear correctly on the client
side. Instead, the session graphics are drawn inside a small rectangle on the client side. [#LC7857]
Windows Media Player might display Microsoft AVI (.avi) files format as vertically flipped. [#LC8308]
User Int erf ace
If you open a spreadsheet with more than one workbook in Excel 2010, the taskbar displays only the most current
workbook. [#LC7557]
Desktop wallpaper appears even after setting the "Desktop wallpaper" policy to "Prohibited." [#LC8398]
VDA for Server OS
HDX P lug and P lay
USB devices that report the same serial number for more than one device such as Syn-Tech ProKee V2 might not get
redirected to a VDA session. T he following CDF trace appears:
"Failed to assign the instance ID, error 0xc000000d." [#LC8264]
P rint ing
Attempts to launch a published application might fail when the application is waiting for a mutex object in Citrix Print
Manager service (cpsvc.exe). [#LC6829]
T he Citrix Print Manager service (cpsvc.exe) might exit intermittently. [#LC7535]
When you roam a session between clients, session printers cannot be deleted. For example, when you configure the
policy "Printer assignments" – printer A for client A and printer B for client B, printer A might not be deleted when you
roam from client A to client B. [#LC8077]
Server/Sit e Administ rat ion
T he Citrix Stack Control Service (SCService64.exe) might exit unexpectedly when the VDA checks for the group
membership of the user when there are two or more groups with the same name in multiple domains. T he issue occurs
when the string "DnsDomainName" is empty in the DS_DOMAIN_T RUST SW structure. [#LC8484]
Session/Connect ion
T he following warning message might appear in the system event log when launching XenApp 7.6 Long Term Service
Release Cumulative Update 2 VDA for Server OS or the previous versions:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.12
"An attempt to connect to the SemsService has failed with error code 0x2." [#LC6311]
Attempts to reconnect to an application might fail. T he issue occurs when any of the disconnected application becomes
unresponsive when the session disconnected initially. [#LC6550]
When you click "Cancel" on the progress bar of a session launch, wrong session information can remain on the Delivery
Controller. As a result, the actual session is not created on the VDA and you might not be able to launch a new session.
[#LC6779]
After undocking a laptop, session sharing might fail. T he issue occurs when the VDA reregisters with the Delivery
Controller while an-out-of-order notification is triggered during auto client reconnect. [#LC7450]
T he microphone might be redirected intermittently in the user session even after setting the "Client microphone
redirection" policy value to "Prohibited."
T his fix addresses the issue. However, if you continue to observe the issue, apply the following registry key on the device
with the microphone:
HKEY_LOCAL_MACHINE\SYST EM\CurrentControlSet\Control\T erminal Server\WinStations\ica-tcp\AudioConfig
Name: MaxPolicyAge
T ype: DWORD
Value: Maximum time (in seconds) allowed between the last policy evaluation and the time of endpoint activation.
Default is 30 seconds.
HKEY_LOCAL_MACHINE\SYST EM\CurrentControlSet\Control\T erminal Server\WinStations\ica-tcp\AudioConfig
Name: PolicyT imeout
T ype: DWORD
Value: Maximum time (in milliseconds) that the system waits for policies after determining that the policies are not up
to date. Default is 4,000 milliseconds. When the timeout occurs, the system reads the policies and continues with
initialization. Setting this value to (0) bypasses the Active Directory policies check and processes policies immediately.
[#LC7495]
When you establish a Skype for Business video call, a blue window border might appear after intersecting with the
window of a third party application. [#LC7773]
Certain published applications might not cover the entire screen when maximized. [#LC7854]
After upgrading to Versions 7.13, 7.14, or 7.15 of a VDA when using vGPU, a black area might appear in published
applications or desktops running on the Microsoft Windows Server operating system. [#LC7875]
When performing an insert operation between two Microsoft Excel 2010 worksheets running on a Version 7.9 VDA, the
Excel window might become unresponsive. [#LC7912]
In certain scenarios, seamless applications might not appear in seamless mode or certain features might not work.
[#LC8030]
With local app access enabled, using the interactive logon disclaimer policy can cause the desktop viewer to show a gray
screen when connecting to a VDA. [#LC8136]
VDAs for Server OS might reregister intermittently when an out-of-order notification is sent to the Delivery Controllers.
[#LC8228]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.13
When you launch an application with session lingering enabled, the session might log off after the application appears.
[#LC8245]
Servers might become unresponsive on RPM.dll and the following error message appears:
"Event ID 1009, picadm: T imeout waiting for response message from client" [#LC8339]
Windows Explorer might close unexpectedly in one of the following cases:
When selecting a large number of files whose names contain more than 260 characters and then selecting the "Send
to > Fax recipient" option.
When attempting to open third-party applications.
When attempting to combine files by using Nitro PDF. [#LC8423]
Smart Cards
When you log on to a session using a smart card, the session might become unresponsive until you disconnect and
reconnect the session. [#LC8036]
Syst em Except ions
T he wfshell.exe process might exit unexpectedly, pointing to the taskbar grouping module. [#LC6968]
On systems with Hotfix Rollup Pack 7 installed, servers might experience a fatal exception, displaying a blue screen, on
picadm.sys with bugcheck code 0x00000050 (PAGE_FAULT _IN_NONPAGED_AREA). [#LC6985]
T he Windows Shell Experience Host might exit unexpectedly when you click the volume control on the taskbar.
[#LC7000]
Servers might experience a fatal exception, displaying a blue screen, on picadm.sys with bugcheck code 0x22. [#LC7574]
T he Service Host (svchost.exe) process might experience an access violation and exit unexpectedly. T he issue occurs
because of the faulting module, icaendpoint.dll. [#LC7900]
With the USB redirection policy enabled, VDAs might experience a fatal exception, displaying a blue screen with bugcheck
code SYST EM_T HREAD_EXCEPT ION_NOT _HANDLED (7e). [#LC7999]
Servers might experience a fatal exception, displaying a blue screen, on picavc.sys with bugcheck code
SYST EM_T HREAD_EXCEPT ION_NOT _HANDLED (7e). [#LC8063]
User Experience
When reconnecting to a seamless application session, the application windows might not appear correctly on the client
side. Instead, the session graphics are drawn inside a small rectangle on the client side. [#LC7857]
Windows Media Player might display Microsoft AVI (.avi) files format as vertically flipped. [#LC8308]
User Int erf ace
If you open a spreadsheet with more than one workbook in Excel 2010, the taskbar displays only the most current
workbook. [#LC7557]
Desktop wallpaper appears even after setting the "Desktop wallpaper" policy to "Prohibited." [#LC8398]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.14
Virtual Desktop Components - Other
T he Microsoft Office KMS activation might fail when using Machine Creation Services (MCS). T he issue occurs when
Microsoft Office on the master image in MCS cannot be rearmed.[#LC6214]
Other fixed issues
T he parameter AppVApplications of the object returned by Get-AppLibAppVPackage is a blank array, even though
applications exist for that package and can be retrieved using Get-AppLibAppVApplication cmdlet. (After fixing, GetAppLibAppVPackage returns a populated array of AppVApplications if you call it with -RetrieveApplicationData $true.
[#DNA-23524]
When installing components using the AutoSelect application on the installation media, the autorun.log file might
contain errors and exceptions about insufficient rights. Provided the installation completed successfully, you can ignore
these errors. [#DNA-45937]
When the cmdlet Get-ApplibAppVApplicationInfo is executed a Permission Denied error is raised. [#DNA-46589]
T he policy settings are not saved in the Printer driver mapping and compatibility policy. [#DNA-47423]
Stopping or restarting the Citrix Print Manager Service may leave the CpSvc.exe process in an unresponsive state. [#HDX10071]
Published content will not start successfully when initiated from Citrix Receiver. Content launched through the
StoreFront web client (or Web Interface) launches as expected [#LC6316, RFWIN-4957]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.15
Known issues
Feb 0 1, 20 18
T he following 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.
XenApp and XenDesktop
T he XenApp and XenDesktop 7.16 release contains the following issues:
When you select machines and add them to existing Delivery Groups, Studio allows you to add machines from
incompatible Machine Catalogs to the same Delivery Group. (If you first select a Delivery Group and add machines to it,
Studio correctly prevents machines from incompatible Machine Catalogs being added.)
[#DNA-39589]
When you remove an App-V package from the Application Library, it is removed from the Studio display, but not from the
VDA.
[#DNA-47379]
When App-V applications are disabled on the App-V management server, they are still listed in Studio in the App-V
Publishing node, even though they cannot be used. T o hide the disabled applications, restart Studio.
[#DNA-50304]
App-V shortcuts published as applications in XenApp do not launch, and raise an error, if their shortcut command line
arguments contain Virtual File System replaceable tokens, such as [{Common Programs}] or [{ProgramFilesX64}]. T o
avoid this issue, sequence the package shortcuts without replaceable tokens.
[#DNA-52772]
An intermittent (observed when the Windows CEIP process runs nightly) StoreFront upgrade issue occurs during an
upgrade from a 7.12 of later Delivery Controller. T he following message is displayed:
"StoreFront cannot be upgraded because the following program is using some files. Close the program and try again.
Program name: CompatTelRunner"
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.16
To work around this issue, follow the instruction in the message.
[#DNA-51341]
If StoreFront was originally installed using the executable from the installation media, StoreFront does not appear as
eligible for upgrade when you use the full-product installer for a later version. As a workaround, upgrade StoreFront using
the executable from the installation media.
[#DNA-47816]
When upgrading a XenDesktop 5.6 deployment, group policy is missing. As a workaround, first upgrade from XenDesktop
5.6 to XenDesktop 7.13. T hen upgrade to the current release.
[#DNA-44818]
When installing a Controller and you select I want t o connect t o Smart T ools and Call Home on the Smart T ools
page of the installation wizard, Call Home might not be enabled. As a workaround, either use the schedule feature in
Citrix Scout or enable Call Home using PowerShell.
[#CAM-9907]
When upgrading the Delivery Controller from a version earlier than 7.13, to version 7.13 and later, an error (exception) may
be seen if the "Auto client reconnect timeout" setting is configured in any of the policies. T his error happens if the "Auto
client reconnect timeout" setting value is outside the permitted range 0 and 300, which was first introduced in version
7.13. T o prevent this error, use the Citrix Group Policy PowerShell Provider to unconfigure the setting, or to set it to a
value within the specified range. For an example, see CT X22947.
[#DNA-52476]
When upgrading a Delivery Controller from version 7.15 CU1 to version 7.16, a Citrix licensing error message might appear.
You can safely click OK and ignore this message.
[#DNA-52820]
Citrix Studio allows assignment of multiple Desktop Assignment Rules (DAR) for different users or user groups to a single
VDA in the Delivery Group. StoreFront displays the assigned desktop with the corresponding Display Name as per the
DAR for the logged in user. However, Director does not support DARs and displays the assigned desktop using the
Delivery Group name regardless of the logged in user. As a result, you cannot map a specific desktop to a machine in
Director.
Workaround : T o map the assigned desktop displayed in StoreFront to the Delivery Group name displayed in Director,
use the following PowerShell command:
Get-BrokerDesktopGroup | Where-Object { $_.Uid -eq (Get-BrokerAssignmentPolicyRule | Where-Object {
$_.PublishedName -eq "<Name on StoreFront>" }).DesktopGroupUid } | Select-Object -Property Name, Uid
[#DNA 53578]
If using HDX Adaptive T ransport with Citrix Receiver for Windows in a LAN environment with NetScaler Gateway, we
recommend that you upgrade to Citrix Receiver for Windows 4.10. Older Citrix Receivers might experience fragmentation
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.17
issues with DT LS.
[#HDX-2149]
A stop error (blue screen) is intermittently observed during the installation of a 7.16 VDA on a Surface Pro 3 or 4. During
installation, the Intel driver igdkmd64 stops responding. T his is a third-party issue that impacts Intel GPUs: Intel 5000 HD,
and Intel Iris 530.
[# HDX-12662]
T he cursor in a session with GPU does not display as expected (black cursor or "ghosting") in Citrix Receiver for Linux or
Citrix Receiver for HT ML5. T he issue will occur for users who have a GPU but do not have the "Optimize for 3d
Workload" policy enabled. T o work around this issue, enable the policy or set the DWORD registry key:
HKLMSOFT WARE\Citrix\HDX3D\BitmapRemotingConfig\EnableDDAPICursor = 1
[# HDX-12366]
Windows Event Log Error: "Windows is unable to verify the image integrity of the file MfApHook64.dll". For more
information, see CT X226397.
[HDX-9063]
When you start an application from StoreFront, the application might not start in the foreground or the application is in
the foreground but might not have focus. As a workaround, click the icon in the task bar to bring the application to the
front or in the application screen to bring it to focus.
[#HDX-10126]
When you delete an Azure Resource Manager machine catalog, the associated machines and resource groups are
deleted from Azure, even if you indicate that they should be retained.
[#DNA-37964]
Multicast might fail to display video when using Citrix Receiver for Windows newer than version 4.6. Audio is still available.
As a workaround, add this registry key on the endpoint:
HKEY_CURRENT _USER\Software\Citrix\HdxMediaStream\
Name: DisableVMRSupport
Type: DWORD
Value: 4
[#HDX-10055]
When LogonUISuppression is enabled, users have these issues:
Users attempting Smartcard authentication cannot log on to use their published applications.
Users are unable to change their passwords using CT RL+ F 1 >> Change password , and they cannot unlock their
machine after locking their session using CT RL+ F 1 >> Lock .
As a workaround, disable LogonUISuppression.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.18
[#HDX-11413, #HDX-12465]
When a user starts a published application and immediately starts a desktop (or tries the reverse order), the second
request might fail with the following error message: T he t ask you are t rying t o do can't be complet ed because
Remot e Deskt op Services is current ly busy. P lease t ry again in a f ew minut es. Ot her users should st ill be
able t o log on. As a workaround, retry after a few seconds.
[#HDX-12492]
Universal Print Server printers selected on the virtual desktop do not appear in the Devices and P rint ers window in
Windows Control Panel. However, when users are working in applications, they can print using those printers. T his issue
occurs only on the Windows Server 2012, Windows 10 and Windows 8 platforms. For more information, see Knowledge
Center article CT X213540. [#335153]
Citrix and Microsoft have identified an issue when starting seamless applications from a Server VDA running Windows
Server 2016. When a user starts an application published from this VDA, Citrix Receiver displays a black screen covering
the workspace of the monitor for several seconds before starting the application. For more information,
see https://support.citrix.com/article/CT X225819.
Warning : If you are using Azure Active Directory (AAD), do not make the registry change described in CT X225819.
Making this change may cause session launch failures for AAD users.
[#HDX-5000, HDX-11255]
After starting a YouT ube video using the YouT ube HT ML5 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]
Other components
Components and features that are documented separately have their own known issues articles.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.19
Third party notices
Nov 28 , 20 17
T his release of XenApp and XenDesktop may include third party software licensed under the terms defined in the following
documents:
XenApp and XenDesktop Third Party Notices
Non-Commercial Software Disclosure For FlexNet Publisher 2016 R1 (11.14.0.0)
FLEXnet Publisher Documentation Supplement: Open Source Software Licenses
applicable to FlexNet Publisher 11.14.0
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.20
Deprecation
Nov 28 , 20 17
T he announcements in this article are intended to give you advanced notice of platforms, Citrix products, 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.
T he 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 this release but they will be removed in
a future Current Release. Items marked with an asterisk (*) are supported up to and including the next XenApp and
XenDesktop Long Term Service Release (LT SR) release.
Removed items are either removed— or are no longer supported— in XenApp and XenDesktop 7.16.
Deprecat ion
in
It em
Removed
in
Alt ernat ive
No alternative for XenApp
and XenDesktop version 7.16 or
VDA support for policy setting "Automatic
installation of in-box printer drivers".
7.16
Support for the Linux VDA on SUSE Linux
Enterprise Server 11 Service Pack 4.
7.16
7.16
Install Linux VDA on supported SUSE
version.
Support for Citrix WDDM driver on VDAs.
7.16
7.16
T he Citrix WDDM driver is no longer
installed with VDAs.
Mobility SDK / Mobile SDK (from the former
Citrix Labs)
7.16
on Windows 8 and newer desktop
operating systems, and
Windows Server 2012 R2 and newer
server operating systems.
VDAs on Windows 10 version 1511 (T hreshold
7.15
2) and earlier Windows desktop OS releases,
including Windows 8.x and Windows 7.
LT SR (and
7.12)
https://docs.citrix.com
7.16
later VDAs. In earlier XenApp
and XenDesktop versions, this
policy setting is not supported
Superseded by mobile experience
policy settings, and native experiences
for hosted desktops/apps.
Install desktop OS VDAs on Windows
10 minimum version 1607 (Redstone 1)
7.16
or newer Semi-Annual Channels. If
using 1607 LT SB, we recommend
a 7.15 VDA. See What's new.
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.21
7.15
LT SR (and
7.12)
7.16
DirectX Command Remoting (DCR).
7.15 LT SR
7.16
Citrix Receiver for Web classic
7.15 LT SR
(and
VDAs on Windows Server 2008 R2
and Windows Server 2012.
experience (“green bubbles” user interface).
Delivery Controllers on Windows Server 2012
and 2008 R2.
Studio on Windows 7.
Flash Redirection.
Install server OS VDAs on supported
versions such as Windows Server 2012
R2 or Windows Server
2016. See What's new.
Use T hinwire.
Citrix Receiver for Web unified
StoreFront
3.12)
experience.
7.15 LT SR
Install Delivery Controllers on an
alternative supported operating
system
7.15 LT SR
Install Studio on an alternative
supported operating system.
Create video content as
HT ML5 Video. Use HT ML5
Video Redirection for
managed content, and Browser
7.15 LT SR
Content Redirection for public web
sites. For more information, see
the Flash Redirection End of
Life note.
Citrix Online Integration (Goto product) with
StoreFront.
7.14 (and
StoreFront
3.11)
StoreFront
3.12
T he user account, CtxAppVCOMAdmin, which
was created during VDA installation and added
to the Local Administrators Group on the
VDA machine, is no longer created.
T he underlying "COM" mechanism is
T he Windows service CtxAppVService
7.14
7.14
also removed.
performs the same function. It is
automatically installed and configured
and requires no user interaction.
T he Universal Print Server
UpsServer component support on Windows
Server 2008 32-bit.
StoreFront and Receiver for Web on Internet
Explorer 8.
7.14
7.14
7.13
7.13
Use one of the other
supported platforms.
T he VDA command line installation
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.22
option /no_appv to prevent installation of
the Citrix App-V components.
7.13
7.13
Use the command line installation
option /exclude "Citrix Personalization
for App-V – VDA".
Some PowerShell commands that
were provided by
the Citrix.Common.Commands snap-in
T he full-product installer no longer installs the
Citrix.Common.Commands snap-in on new
installations and automatically removes it
when upgrading existing installations.
7.13
7.13
are still available in the XenApp 6.5
SDK. For more information,
see XenApp and XenDesktop version
7.13
Removed features.
Partial functionality to manipulate icon data
that was provided by *-CtxIcon cmdlets.
7.13
7.13
Now provided by *-BrokerIcon cmdlets
in the Broker Service.
Use T hinwire. If you are using Legacy
T hinwire mode on Windows Server
Legacy T hinwire mode.
7.12
7.16
2008 R2, migrate to Windows Server
2012 R2 or Windows Server 2016,
and use T hinwire.
In-place upgrades from StoreFront 2.0, 2.1, 2.5,
and 2.5.2.
Upgrade from one of these versions to
7.13
7.16
a later supported version and then to
XenApp and XenDesktop 7.16.
Migrate your XenDesktop 5.6 or 5.6
In-place upgrades from XenDesktop 5.6 or 5.6
FP1.
7.12
7.16
FP1 deployment to the current
XenDesktop version. T o do this, first
upgrade to XenDesktop 7.6, then
upgrade to the current XenDesktop
current release or LT SR version.
Installing core components on 32bit machines: Delivery Controller,
Director, StoreFront, and License Server.
7.12
7.16
Use 64-bit machines.
Connection leasing.
7.12
7.16
Use Local Host Cache.
7.12
7.16
XenDesktop 5.6 used on Windows XP. No VDA
installations on Windows XP are supported.
CloudPlatform connections.
7.12
Azure Classic (also known as Azure Service
Management) connections.
7.12
HDX Desktop Composition Redirection (DCR)
7.12
https://docs.citrix.com
Install VDAs on a supported Windows
version. See What's new.
Use a different supported hypervisor
or cloud service
Use Azure Resource Manager.
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.23
T he AppDisks and Personal vDisk functionality provided by XenApp and XenDesktop is now deprecated for current
releases*. Citrix is replacing this functionality with recently acquired technology from Unidesk (Citrix App Layering). During
this transition time, Citrix continues to maintain current support levels as described in XenApp and XenDesktop Servicing
Options.
* AppDisks and Personal vDisk are not covered by the Long Term Service Releases (LT SR) servicing option.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.24
System requirements
Jan 18 , 20 18
In this article:
Introduction
Delivery Controller
Databases
Citrix Studio
Citrix Director
Virtual Delivery Agent (VDA) for Desktop OS
Virtual Delivery Agent (VDA) for Server OS
Hosts / virtualization resources
Active Directory functional levels
HDX
Universal Print Server
Other
Introduction
T he system requirements in this document were valid when this product version released; updates are made periodically.
System requirements components not covered here (such as StoreFront, host systems, Citrix Receivers and plug-ins, and
Provisioning Services) are described in their respective documentation.
Import ant : Review the Prepare to install article before beginning an installation.
Unless otherwise noted, the component installer deploys software prerequisites automatically (such as .NET and C++
packages) if the required versions are not detected on the machine. T he Citrix installation media also contains some of this
prerequisite software.
T he 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 CT X119253.
For XenApp and XenDesktop components and features that can be installed on Windows Servers, Server Core and Nano
Server installations are not supported, unless specifically noted.
For components and features that can be used on Windows 10 machines, the following Windows 10 servicing options and
editions are supported:
Semi-annual Channel: Pro, Enterprise, Education, Mobile Enterprise (the IoT Core Pro Edition is supported only for Citrix
Receiver).
Long-term Servicing Channel (LT SC): Enterprise LT SB Edition
For further details, see CT X224843.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.25
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. T his includes the features you use, plus the
number of users, and other factors. Using only the minimum can result in slow performance.
T he following table shows the minimum requirements for core components.
Component
Minimum
All core components on one server, for an evaluation only,
5 GB RAM
not a production deployment
All core components on one server, for a test deployment
12 GB RAM
or a small production environment
Delivery Controller
5 GB RAM
(more disk space required for Local Host Cache)
800 MB hard disk
Database: see the Sizing guidance article
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
License Server
2 GB RAM
See the Licensing documentation for disk
recommendations
Sizing of VMs t hat deliver deskt ops and applicat ions
Specific recommendations cannot be provided because of the complex and dynamic nature of hardware offerings, and
every XenApp and XenDesktop deployment has unique needs. Generally, sizing a XenApp VM is based on the hardware and
not the user workloads (except for RAM; you'll need more RAM for applications that consume more).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.26
T he Sizing XenApp Windows 2012 R2 Virtual Machines blog post contains sizing considerations.
T he Citrix Synergy 2016 video (start at 1:15:00) discusses differences between sizing VMs to deliver applications and sizing
to deliver desktops. It also covers scalability estimates: how many users to expect from a single server. Although based
on a shared desktop model, the tests measure capacity to reach maximum CPU utilization, using one application at a
time. Changing applications should have minimal impact on overall density.
Delivery Controller
Supported operating systems:
Windows Server 2016, Standard and Datacenter Editions
Windows Server 2012 R2, Standard and Datacenter Editions
Windows Server 2012, Standard and Datacenter Editions
Windows Server 2008 R2 SP1, Standard, Enterprise, and Datacenter Editions
Requirements:
Microsoft .NET Framework 3.5.1 (Windows Server 2008 R2 only).
Microsoft .NET Framework 4.5.2 (4.6 through 4.7 are also supported).
Windows PowerShell 3.0 or later.
Microsoft Visual C++ 2015 Runtime, 32- and 64-bit.
Databases
Supported Microsoft SQL Server versions for the Site Configuration, Configuration Logging, and Monitoring databases:
SQL Server 2017, Express, Standard, and Enterprise Editions.
SQL Server 2016, Express, Standard, and Enterprise Editions.
SQL Server 2014 through SP2, Express, Standard, and Enterprise Editions. By default, SQL Server 2014 SP2 Express is
installed when installing the Controller, if an existing supported SQL Server installation is not detected.
SQL Server 2012 through SP3, Express, Standard, and Enterprise Editions.
SQL Server 2008 R2 SP2 and SP3, Express, Standard, Enterprise, and Datacenter Editions.
T he 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.
When installing a Controller, a SQL Server Express database is installed by default for use with the Local Host Cache
feature. T his installation is separate from the default SQL Server Express installation for the Site database.
For more information, see the following articles:
Databases
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.27
CT X114501
Database sizing guidance
Local Host Cache
Citrix Studio
Supported operating systems (IMP ORT ANT : 32-bit only; 64-bit versions are not supported):
Windows 10 (see edition support in the Introduction section)
Windows 8.1, Professional and Enterprise Editions
Windows 7 Professional, Enterprise, and Ultimate Editions
Windows Server 2016, Standard and Datacenter Editions
Windows Server 2012 R2, Standard and Datacenter Editions
Windows Server 2012, Standard and Datacenter Editions
Windows Server 2008 R2 SP1, Standard, Enterprise, and Datacenter Editions
Requirements:
Microsoft .NET Framework 4.5.2 (4.6 through 4.7 are also supported)
Microsoft .NET Framework 3.5 SP1 (Windows Server 2008 R2 and Windows 7 only)
Microsoft Management Console 3.0 (included with all supported operating systems)
Windows PowerShell 2.0 (for Windows 7 and Windows Server 2008 R2), or Windows PowerShell 3.0 or later
Citrix Director
Supported operating systems:
Windows Server 2016, Standard and Datacenter Editions
Windows Server 2012 R2, Standard and Datacenter Editions
Windows Server 2012, Standard and Datacenter Editions
Windows Server 2008 R2 SP1, Standard, Enterprise, and Datacenter Editions
Requirements:
Microsoft .NET Framework 4.5.2 (4.6 through 4.7 are also supported).
Microsoft .NET Framework 3.5 SP1 (Windows Server 2008 R2 only)
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 these are not already installed, you are prompted for the Windows Server installation media, then
they are installed for you.
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. (You can use Internet Explorer 10 only on Windows Server 2012 R2 machines.) Compatibility mode is
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.28
not supported for Internet Explorer. You must use the recommended 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 T ools > Internet Options > Advanced >
Reset and follow the instructions.
Microsoft Edge.
Firefox ESR (Extended Support Release).
Chrome.
T he recommended optimal screen resolution for viewing Director is 1366 x 1024.
Virtual Delivery Agent (VDA) for Desktop OS
Supported operating systems:
Windows 10, minimum version 1607.
See edition support in the Introduction section.
Desktop composition redirection and legacy graphics mode are not supported on Windows 10.
For Citrix known issues with version 1709, see CT X229052.
Requirements:
Microsoft .NET Framework 4.5.2 (4.6 through 4.7 are also supported)
Microsoft Visual C++ 2013 and 2015 Runtimes, 32- and 64-bit
Remote PC Access uses this VDA, which you install on physical office PCs. T his VDA supports Secure Boot for XenDesktop
Remote PC Access on Windows 10.
Several multimedia acceleration features (such as HDX MediaStream Windows Media Redirection) require 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 desktop OS editions, Media Foundation support is already installed and cannot be removed.
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 Desktop OS on
Windows Server 2016. See Server VDI for guidance.
Virtual Delivery Agent (VDA) for Server OS
Supported operating systems:
Windows Server 2016, Standard and Datacenter Editions
Windows Server 2012 R2, Standard and Datacenter Editions
T he installer automatically deploys the following requirements, which are also available on the Citrix installation media in the
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.29
Support folders:
Microsoft .NET Framework 4.5.2 (4.6 through 4.7 are also supported)
Microsoft Visual C++ 2013 and 2015 Runtimes, 32- and 64-bit
T he 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) require 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. 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.
If Media Foundation is not present on the VDA, these multimedia features do not work:
Flash Redirection
Windows Media Redirection
HT ML5 Video Redirection
HDX Realtime Webcam Redirection
For Linux VDA information, see the Linux Virtual Delivery Agent articles.
Hosts / virtualization resources
Some XenApp and XenDesktop features may not be supported on all host platforms or all platform versions. For example,
AppDisks are supported with XenServer, VMware, and System Center Virtual Machine Manager hosts. See the feature
documentation for details.
T he Remote PC Access Wake on LAN feature requires Microsoft System Center Configuration Manager minimum 2012.
Support ed host plat f orms and virt ualizat ion environment s
IMP ORT ANT : T he following major.minor versions are supported, including updates to those versions. CT X131239 contains
the most current hypervisor version information, plus links to known issues.
XenServer
XenServer 7.3
XenServer 7.2
XenServer 7.1
XenServer 7.0
XenServer 6.5 and SP1
XenServer 6.2 SP1 plus hotfixes (you must apply SP1 to enable application of future hotfixes)
XenServer 6.1
VMware vSphere (vCenter + ESXi). No support is provided for vSphere vCenter Linked Mode operation.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.30
VMware vSphere 6.5
VMware vSphere 6.0
VMware vSphere 5.5
VMware vSphere 5.1
VMware vSphere 5.0
VMware vCenter 5.5 / 6 appliance
System Center Virtual Machine Manager. Includes any version of Hyper-V that can register with the supported System
Center Virtual Machine Manager versions.
System Center Virtual Machine Manager 2016
System Center Virtual Machine Manager 2012 R2
System Center Virtual Machine Manager 2012 SP1
System Center Virtual Machine Manager 2012
Nutanix Acropolis 4.5
Amazon Web Services (AWS)
You can provision applications and desktops on supported Windows server operating systems.
T he Amazon Relational Database Service (RDS) is not supported.
See Citrix XenDesktop on AWS for additional information.
CloudPlatform
T he minimum supported version is 4.2.1 with hotfixes 4.2.1-4.
Deployments were tested using XenServer 6.2 (with Service Pack 1 and hotfix XS62ESP1003) and vSphere 5.1 hypervisors.
CloudPlatform does not support Hyper-V hypervisors.
CloudPlatform 4.3.0.1 supports VMware vSphere 5.5.
See the CloudPlatform documentation (including the Release Notes for your CloudPlatform version) for
more information.
Microsoft Azure
Microsoft Azure Resource Manager
Active Directory functional levels
T he following functional levels for the Active Directory forest and domain are supported:
Windows Server 2016
Windows Server 2012 R2
Windows Server 2012
Windows Server 2008 R2
Windows Server 2008
Windows Server 2003
Windows 2000 native (not supported for domain controllers)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.31
HDX
UDP audio for Multi-Stream ICA is supported on Receiver for Windows and Citrix Receiver for Linux 13.
Echo cancellation is supported on Citrix Receiver for Windows.
See the specific HDX feature support and requirements below.
T he Windows user device or thin client must support or contain:
DirectX 9
Pixel Shader 2.0 (supported in hardware)
32 bits per pixel
1.5 GHz 32-bit or 64-bit processor
1 GB RAM
128 MB video memory on the graphic card or an integrated graphics processor
HDX queries the Windows device to verify that it has the required GPU capabilities, and then automatically reverts to
server-side desktop composition if it does not. List the devices with the required GPU capabilities that do not meet the
processor speed or RAM specifications in the GPO group for devices excluded from Desktop Composition Redirection.
T he minimum available bandwidth is 1.5 Mbps; the recommended bandwidth is 5 Mbps. T hose values incorporate end-toend latency.
T he following clients are supported for Windows Media client-side content fetching, Windows Media redirection, and
realtime Windows Media multimedia transcoding: Citrix Receiver for Windows, Citrix Receiver for iOS, and Citrix Receiver for
Linux.
To use Windows Media client-side content fetching on Windows 8 devices, set the Citrix Multimedia Redirector as a default
program: in Cont rol Panel > P rograms > Def ault P rograms > Set your def ault programs , select Cit rix Mult imedia
Redirect or and click either Set t his program as def ault or Choose def ault s f or t his program. GPU transcoding
requires an NVIDIA CUDA-enabled GPU with Compute Capability 1.1 or higher; see http://developer.nvidia.com/cuda/cudagpus.
T he following clients and Adobe Flash Players are supported:
Citrix Receiver for Windows (for second generation Flash Redirection features) - Second generation Flash Redirection
features require Adobe Flash Player for Other Browsers, sometimes referred to as an NPAPI (Netscape Plugin
Application Programming Interface) Flash Player.
Citrix Receiver for Linux (for second generation Flash Redirection features) - Second generation Flash Redirection
features require Adobe Flash Player for other Linux or Adobe Flash Player for Ubuntu.
Citrix Online plug-in 12.1 (for legacy Flash Redirection features) - Legacy Flash Redirection features require Adobe Flash
Player for Windows Internet Explorer (sometimes referred to as an ActiveX player).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.32
T he major version number of the Flash Player on the user device must be greater than or equal to the major version number
of the Flash Player on the server. If an earlier version of the Flash Player is installed on the user device, or if the Flash Player
cannot be installed on the user device, Flash content is rendered on the server.
T he machines running VDAs require:
Adobe Flash Player for Windows Internet Explorer (the ActiveX player)
Internet Explorer 11 (in non-Modern UI mode). You can use Internet Explorer versions 7-10, but Microsoft supports (and
Citrix recommends using) version 11. Flash redirection requires Internet Explorer on the server; with other browsers, Flash
content is rendered on the server.
Protected mode disabled in Internet Explorer (T ools > Internet Options > Security tab > Enable Protected Mode check
box cleared). Restart Internet Explorer to effect the change.
When installing a VDA for Windows Desktop OS, you can choose to install the HDX 3D Pro version.
T he physical or virtual machine hosting the application can use GPU Passthrough or Virtual GPU (vGPU):
GPU Passthrough is available with: Citrix XenServer; VMware vSphere and VMware ESX, where it is referred to as virtual
Direct Graphics Acceleration (vDGA); and with Microsoft Hyper-V in Windows Server 2016 where it is referred to as
Discrete Device Assignment (DDA).
vGPU is available with Citrix XenServer and VMware vSphere; see https://www.citrix.com/products/xenappxendesktop/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, HDX 3D Pro can be used with supported NVIDIA GRID
cards (see NVIDIA GRID). T he 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 http://www.citrix.com/intel and http://www.intel.com/content/www/us/en/servers/datacenter-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 computer. 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 hardware. 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.33
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 Receiver must be installed.
For more information, see the HDX 3D Pro articles and www.citrix.com/xenapp/3d.
Supported clients: Citrix Receiver for Windows, Citrix Receiver for Mac, and Citrix Receiver for Linux.
Supported video conferencing applications:
Adobe Connect
Cisco WebEx
Citrix GoT oMeeting HDFaces
Google+ Hangouts
IBM Sametime
Media Foundation-based video applications on Windows 8.x, Windows Server 2012, and Windows Server 2012 R2
Microsoft Lync 2010 and 2013
Microsoft Office Communicator
Microsoft Skype 6.7
To use Skype on a Windows client, edit the registry on the client and the server:
Client registry key HKEY_CURRENT _USER\Software\Citrix\HdxRealT ime
Name: DefaultHeight , Type: REG_DWORD, Data: 240
Name: DefaultWidth, Type: REG_DWORD, Data: 320
Server registry key HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\Vd3d\Compatibility
Name: skype.exe, Type: REG_DWORD, Data: Set to 0
Other user device requirements:
Appropriate hardware to produce sound.
DirectShow-compatible webcam (use the webcam default settings). Webcams that are hardware encoding capable
reduces client-side CPU usage.
Webcam drivers, obtained from the camera manufacturer if possible.
Universal Print Server
T he Universal Print Server comprises client and server components. T he UpsClient component is included 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.
T he UpsServer component is supported on:
Windows Server 2016
Windows Server 2012 R2 and 2012
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.34
Windows Server 2008 R2 SP1
Requirement: Microsoft Visual C++ 2013 Runtime, 32- and 64-bit
For VDAs for Windows Server 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
StoreFront 3.0.1 is the minimum supported version with this release. To use the zone preference feature, you must be using
minimum StoreFront 3.7 and NetScaler Gateway 11.0-65.x.
When using Provisioning Services with this release, the minimum supported Provisioning Services version is 7.0.
Only Citrix License Server 11.14 is supported.
T he Microsoft Group Policy Management Console (GPMC) is required if you store Citrix policy 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 XenApp or XenDesktop core component installed), that machine must have
Visual Studio 2015 runtime installed. For more information, see the Microsoft documentation.
Multiple network interface cards are supported.
By default, the Citrix Receiver for Windows is installed when you install a VDA. For more information, see the Citrix Receiver
for Windows documentation.
See App-V for supported versions of Microsoft App-V.
See Local App Access for supported browser information for that feature.
See the Self-Service Password Reset documentation for support and requirements information.
Client folder redirection - Supported operating systems:
Server: Windows Server 2008 R2 SP1, Windows Server 2012, and Windows Server 2012 R2
Client (with latest Citrix Receiver for Windows): Windows 7, Windows 8, and Windows 8.1
Mixed DPIs with multi-monitors. T he use of different DPIs between monitors is not supported in Citrix XenDesktop and
XenApp environments. You can verify the DPI (% scaling) using Windows Control Panel > Display options. If using a Windows
8.1 or Windows 10 client device, enabling the Let me choose one scaling level f or all my displays opt ion in the
Windows Control Panel > Display options will configure the monitors appropriately. For more information, see CT X201696.
T his version of XenApp and XenDesktop is not compatible with AppDNA 7.8 and AppDNA 7.9. Citrix recommends using the
current AppDNA release.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.35
Technical overview
Nov 28 , 20 17
In this article:
Key XenApp and XenDesktop components
How typical deployments work
How user connections are handled
How data access works
Deliver desktops and applications: Machine Catalogs, Delivery Groups, and Application Groups
XenApp and XenDesktop are virtualization solutions that give IT control of virtual machines, applications, licensing, and
security while providing anywhere access for any device.
XenApp and XenDesktop 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 devices.
Administrators to manage an entire network from a single data center.
XenApp and XenDesktop share a unified architecture called FlexCast Management Architecture (FMA). FMA's key features
are the ability to run multiple versions of XenApp or XenDesktop from a single Site and integrated provisioning.
Key XenApp and XenDesktop components
T ip: T his article is most helpful if you're new to XenApp or XenDesktop. If you currently have a 6.x or earlier XenApp farm, or
a XenDesktop 5.6 or earlier site, take a look at the Changes in 7.x article, too.
T his illustration shows the key components in a typical XenApp or XenDesktop deployment, which is called a Site.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.36
Delivery Cont roller
T he Delivery Controller is the central management component of a XenApp or XenDesktop 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,
Controllers should be installed on more than one server. If your deployment includes virtual machines hosted on a
hypervisor or cloud service, the Controller services communicate with the hypervisor to distribute applications and
desktops, authenticate and manage user access, broker connections between users and their virtual desktops and
applications, optimize use connections, and load-balance these connections.
T he 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. T he 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.
T he Monitor Service collects historical data and places it in the Monitor database. T his service uses TCP port 80 or
443.
Data from the Controller services is stored in the Site database.
T he Controller manages the state of desktops, starting and stopping them based on demand and administrative
configuration. In some editions, the Controller allows you to install Profile management to manage user
personalization settings in virtualized or physical Windows environments.
Dat abase
At least one Microsoft SQL Server database is required for every XenApp or XenDesktop Site to store configuration
and session information. T his 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.
T he Site also uses a Configuration Logging database and a Monitoring database. By default, these are installed in the
same location as the Site database, but you can change this.
Virt ual Delivery Agent (VDA)
T he VDA is installed on each physical or virtual machine in your Site that you make available to users; those machines
can deliver applications or desktops. T he 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, verify that a Citrix license is available for the user or session, and apply
whatever policies have been configured for the session.
T he VDA communicates session information to the Broker Service in the Controller through the broker agent included
in the VDA. T he broker agent hosts multiple plugins and collects real-time data. It communicates with the Controller
over TCP port 80.
T he word "VDA" is often used to refer to the agent as well as the machine on which it is installed.
VDAs are available for Windows server and desktop operating systems. VDAs for Windows server operating systems
allow multiple users to connect to the server at one time. VDAs for Windows desktop operating systems allow only
one user to connect to the desktop at a time. A Linux VDA is also available.
Cit rix St oreF ront
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.37
StoreFront authenticates users to Sites hosting resources, 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 to ensure users have a consistent experience across multiple devices.
Cit rix Receiver
Installed on user devices and other endpoints (such as virtual desktops), Citrix Receiver provides users with quick,
secure, self-service access to documents, applications, and desktops from any of the user's devices, including
smartphones, tablets, and PCs. Citrix Receiver provides on-demand access to Windows, Web, and Software as a
Service (SaaS) applications. For devices that cannot install Citrix Receiver software, Citrix Receiver for HT ML5 provides
a connection through a HT ML5-compatible web browser.
Cit rix St udio
Studio is the management console that enables you to configure and manage your XenApp and XenDesktop
deployment, eliminating the need for separate management consoles for managing delivery of applications and
desktops. Studio provides various wizards to guide you through the process of setting up your environment, creating
your 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.
Cit rix Direct or
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 XenApp or XenDesktop 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 NetScaler 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 Assistance.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.38
Cit rix License Server
T he License Server manages your Citrix product licenses. It communicates with the Controller to manage licensing for
each user's session and with Studio to allocate license files. You must create at least one license server to store and
manage your license files.
Hypervisor or cloud service
T he hypervisor or cloud service hosts the virtual machines in your Site. T hese can be the VMs you use to host
applications and desktops, as well as VMs you use to host the XenApp and XenDesktop components. A hypervisor is
installed on a host computer dedicated entirely to running the hypervisor and hosting virtual machines.
XenApp and XenDesktop support a variety of hypervisors and cloud services.
Although many XenApp and XenDesktop deployments require a hypervisor, you don't need one to provide Remote PC
Access or when you are using Provisioning Services (included with some editions of XenApp and XenDesktop) instead
of Machine Creation Services (MCS) to provision VMs.
For more information about:
Ports, see Network ports.
Databases, see Databases.
Windows services in XenApp and XenDesktop components, see Configure user rights.
Supported hypervisors and cloud services, see System requirements.
T he following additional components, not shown in the illustration above, can also be included in XenApp or XenDesktop
deployments. For more information, see their documentation.
P rovisioning Services (P VS)
PVS is an optional component of XenApp and XenDesktop available with some editions. It provides an alternative to
MCS for provisioning virtual machines. Whereas MCS creates copies of a master image, PVS streams the master image
to user device. PVS doesn’t require a hypervisor to do this, so you can use it to host physical machines. When PVS is
included in a Site, it communicates with the Controller to provide users with resources.
Net Scaler Gat eway
When users connect from outside the corporate firewall, XenApp and XenDesktop can use Citrix NetScaler Gateway
(formerly Access Gateway) technology to secure these connections with T LS. T he NetScaler Gateway or NetScaler
VPX virtual appliance is an SSL VPN appliance that is deployed in the demilitarized zone (DMZ) to provide a single
secure point of access through the corporate firewall.
Net Scaler SD-WAN
In deployments where virtual desktops are delivered to users at remote locations such as branch offices, Citrix
NetScaler SD-WAN (formerly Citrix CloudBridge, Branch Repeater, or WANScaler) technology can be employed to
optimize performance. Repeaters accelerate performance across wide-area networks, so with repeaters in the
network, users in the branch office experience LAN-like performance over the WAN. NetScaler SD-WAN can prioritize
different parts of the user experience so that, for example, the user experience does not degrade in the branch
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.39
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 XenApp and XenDesktop 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 XenApp or XenDesktop Site consists of VDA-installed servers and
desktop machines, and the Delivery Controller, which manages access.
T he VDA enables users to connect to desktops and applications. It is installed on server or desktop machines in the data
center for most delivery methods, but it can also be installed on physical PCs for Remote PC Access.
T he 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, and because sessions are dependent on
latency, bandwidth, and network reliability, all Controllers ideally should be on the same LAN.
Users never directly access the Controller. T he VDA serves as an intermediary between users and the Controller. When users
log on to the Site using StoreFront, their credentials are passed through to the Broker Service on the Controller, which
obtains their profiles and available resources based on the policies set for them.
How user connections are handled
To start a XenApp or XenDesktop session, the user connects either through Citrix Receiver, which is installed on the user's
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.40
device, or a StoreFront Citrix Receiver for Web site.
T he user selects the physical or virtual desktop or virtual application that is needed.
T he 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 administrators place an SSL certificate on StoreFront to
encrypt the credentials coming from Citrix Receiver.
T he 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 Receiver pathway. When the user selects applications or desktops from this list, that information goes
back down the pathway to the Controller, which determines the proper VDA to host the specific applications or desktop.
T he 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. T he VDA accepts the connection and sends the information back through the same pathways to
Citrix Receiver. A set of required parameters is collected on StoreFront. T hese parameters are then sent to Citrix Receiver,
either as part of the Receiver-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.
T he 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. T his connection bypasses the management infrastructure (Citrix Receiver, StoreFront, and Controller).
T he connection between Citrix Receiver 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.41
After the client connects to the VDA, the VDA notifies the Controller that the user is logged on, and the Controller sends
this information to the Site database and starts logging data in the Monitoring database.
How data access works
Every XenApp or XenDesktop session produces data that IT can access through Studio or Director. Using Studio,
administrators can access real-time data from the Broker Agent to better manage sites. Director accesses to the same
real-time data plus historical data stored in the Monitoring database, as well as 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 providing real-time data. T he
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; therefore, it accesses only to real-time data. Director communicates
with the Broker Service (through a plugin in the Broker Agent) to access the Site database.
Director can also access NetScaler Gateway to get information on the HDX data.
Deliver desktops and applications: Machine Catalogs,
Delivery Groups, and Application Groups
You set up the machines that will deliver applications and desktops with Machine Catalogs. T hen, you create Delivery
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.42
Groups that specify the applications and desktops that will be available (using some or all of the machines in the catalogs),
and which users can access them.
Machine Cat alogs
Machine Catalogs are collections of virtual or physical machines that you manage as a single entity. T hese 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. T hey 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 (PVS 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 thirdparty electronic software distribution (ESD) tools.
Valid machine types are:
Server OS machines : Virtual or physical machines based on a server operating system used for delivering XenApp
published apps, also known as server-based hosted applications, and XenApp published desktops, also known as serverhosted desktops. T hese machines allow multiple users to connect to them at one time.
Deskt op OS machines : Virtual or physical machines based on a desktop operating system used for delivering VDI
desktops (desktops running desktop operating systems that can be fully personalized, depending on the options you
choose), and VM-hosted apps (applications from desktop operating systems) and hosted physical desktops. Only one
user at a time can connect each of these desktops.
Remot e P C Access : Enables remote users to access their physical office PCs from any device running Citrix Receiver.
T he office PCs are managed through the XenDesktop deployment, and require user devices to be specified in a
whitelist.
For more information, see the Create Machine Catalogs article.
Delivery Groups
Delivery Groups specify which users can access which applications and/or desktops on which machines. Delivery Groups
contain machines from your Machine Catalogs, and Active Directory users who have access to your Site. It often makes
sense to assign users to your Delivery Groups by their Active Directory group because both Active Directory groups and
Delivery Groups are ways of grouping users with similar requirements.
Each Delivery Group can contain machines from more than one Machine Catalog, and each catalog can contribute
machines to more than one Delivery Group, but each individual machine can only belong to one Delivery Group at a time.
You define which resources users in the Delivery Group can access. For example, if you want to deliver different applications
to different users, one way to do this is to install all the applications you want to deliver on the master image for one
Machine Catalog and create enough machines in that catalog to distribute among several Delivery Groups. T hen you
configure each Delivery Group to deliver a different subset of the applications installed on the machines.
For more information, see the Create Delivery Groups article.
Applicat ion 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 additional machines. A tag restriction can be thought of as subdividing (or
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.43
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 the Create Application Groups article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.44
Active Directory
Nov 28 , 20 17
Active Directory is required for authentication and authorization. T he Kerberos infrastructure in Active Directory is used to
guarantee the authenticity and confidentiality of communications with the Delivery Controllers. For information about
Kerberos, see the Microsoft documentation.
T he 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.
T his product supports:
Deployments in which the user accounts and computer accounts exist in domains in a single 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 supported 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 domains containing the virtual desktop computer accounts. In this type of deployment, all domains 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 determine which Controllers
they can register with (discovery). T his 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 the
Delivery Controllers article and CT X118976.
T ip: Do not change the computer name or the domain membership of a Controller after the Site is configured.
Note: T his 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 for name lookup and registration. To allow the appropriate Active Directory users to create computer accounts,
use the Delegation of Control wizard. Refer to Microsoft documentation for more information about this wizard.
No reverse DNS zones are necessary in the DNS infrastructure if appropriate DNS forwarders are in place between forests.
T he SupportMultipleForest key is necessary if the VDA and Controller are in separate forests, regardless of whether the
Active Directory and NetBios names are different. T he SupportMultipleForest key is only necessary on the VDA. Use the
following information to add the registry key:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.45
Caut ion: 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 Registry Editor can be solved. Use Registry Editor
at your own risk. Be sure to back up the registry before you edit it.
HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\SupportMultipleForest
Name: SupportMultipleForest
T ype: REG_DWORD
Data: 0x00000001 (1)
You might need reverse DNS configuration if your DNS namespace is different than that of Active Directory.
If external trusts are in place during setup, the ListOfSIDs registry key is required. T he 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. T o add the registry key, use the following information:
For a 32-bit or 64-bit VDA, locate the registry key
HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\ListOfSIDs
Name: ListOfSIDs
T ype: REG_SZ
Data: Security Identifier (SID) of the Controllers
When external trusts are in place, make the following changes on the VDA:
1. Locate the file <ProgramFiles>\Citrix\Virtual Desktop Agent\brokeragentconfig.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.
T he following table lists the supported trust types:
T rust t ype
T ransit ivit y
Direct ion
Support ed in t his release
Parent and child
T ransitive
T wo-way
Yes
T ree-root
T ransitive
T wo-way
Yes
External
Nontransitive
One-way or two-way
Yes
Forest
T ransitive
One-way or two-way
Yes
Shortcut
T ransitive
One-way or two-way
Yes
Realm
T ransitive or nontransitive
One-way or two-way
No
For more information about complex Active Directory environments, see CT X134971.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.46
Databases
Nov 28 , 20 17
A XenApp or XenDesktop Site uses three SQL Server databases:
Sit e: (also known as Site Configuration) stores the running Site configuration, plus the current session state and
connection information.
Conf igurat ion Logging: (also known as Logging) stores information about Site configuration changes and
administrative activities. T his database is used when the Configuring Logging feature is enabled (default = enabled).
Monit oring: 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 affecting other Controllers in the Site. T his 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. T he backup strategy for each database may differ. For instructions, see CT X135207.
If your Site contains more than one zone, the Site database should always be in the primary zone. Controllers in every zone
communicate with that database.
High availability
T here are several high availability solutions to consider for ensuring automatic failover:
AlwaysOn Availabilit y Groups: T his 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
http://msdn.microsoft.com/en-us/library/hh510230.
SQL Server dat abase mirroring: Mirroring the database ensures that, should you lose the active database server, an
automatic failover process happens in a matter of seconds, so that users are generally unaffected. T his 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 clust ering: T he 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. However, setting up this solution is more complicated, and
the automatic failover process is typically slower than alternatives such as SQL mirroring.
Using t he hypervisor's high availabilit y f eat ures: With this method, you deploy the database as a virtual machine
and use your hypervisor's high availability features. T his 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.
Not e : Installing a Controller on a node in an SQL clustering or SQL mirroring installation is not supported.
T he 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 available. For more information, see the Local
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.47
Host Cache article.
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. T his feature should be used 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
CT X 127564.
Install database software
By default, SQL Server Express edition is installed when you install the first Delivery Controller if another SQL Server instance
is not detected on that server. T hat default action is generally sufficient for proof of concept or pilot deployments;
however, SQL Server Express does not support Microsoft high availability features.
T he 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. T he Controller uses the
Network Service account in this configuration. T he Controller does not require any additional SQL Server roles or
permissions.
If required, you can select Hide inst ance 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. T he
System requirements article lists the supported SQL Server versions. T he 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 Dat abases page in the Site creation wizard; see Database
address formats below. To avoid potential errors when Director queries the Monitor Service, do not use whitespace in the
name of the Monitoring database.
T he Dat abases 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 below.
You can change the location of a database later, after you create the Site; see Change database locations below.
To configure a Site to use a mirror database, complete the following and then proceed with the automatic or scripted
setup procedures.
1. Install the SQL Server software on two servers, A and B.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.48
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.
T ip: To verify mirroring after creating the Site, run the PowerShell cmdlet get -configdbconnect ion 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 the Delivery Controllers
article.
If you have the required database privileges, select the "Create and set up databases from Studio" option on the
Dat abases 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.
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 Generat e script s option. T his 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. T he Site creation wizard stops automatically at this point; you'll be
prompted when you return later to continue the Site creation.
T he database administrator then creates the databases. Each database should have the following characteristics:
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 CT X 137161.
High availability features should be configured, if desired.
T o 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. T hen, start mirroring on the principal server.
T he database administrator uses the SQLCMD command-line utility or SQL Server Management Studio 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 Dat abases page. Enter the addresses.
If any of the servers hosting a database cannot be contacted, an error message is displayed.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.49
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. T he following permissions 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 empty database
dbcreator
Create a schema
Create all service-specific schemas and add the
securityadmin *
db_owner
securityadmin *
db_owner
first Controller to the Site
Add a Controller
Add a Controller (other than the first) to the
Site
Add a Controller (mirror
Add a Controller login to the database server
server)
currently in the mirror role of a mirrored
securityadmin *
database
Update a schema
Apply schema updates or hotfixes
db_owner
* While technically more restrictive, in practice, the securityadmin server role should be treated as equivalent to the
sysadmin server role.
When using Studio to perform these operations, the user account must be a member of the sysadmin server role.
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 databases. When you change the location of a database:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.50
T he data in the previous database is not imported to the new database.
Logs cannot be aggregated from both databases when retrieving logs.
T he 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 Conf igurat ion in the Studio navigation pane.
3. Select the database for which you want to specify a new location and then select Change Dat abase 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. T he 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 Generat e script . T he
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.
For more information
Articles in the Advanced Concepts section contain the most technical and in-depth articles from across the Citrix teams. For
example:
T he Design collection contains an article about a database sizing tool.
T he Implementation and Configuration collections contains guidance for sizing the Site database and configuring
connection strings when using SQL Server high availability solutions.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.51
Delivery methods
Nov 28 , 20 17
It’s challenging to meet the needs of every user with one virtualization deployment. XenApp and XenDesktop allow
administrators to customize the user experience with a variety of methods sometimes referred to as FlexCast models.
T his collection of delivery methods — each with its own advantages and disadvantages — provide the best user experience
in any use-case scenario.
Touch-screen devices, such as tablets and smartphones, are now standard in mobility. T hese devices can cause problems
when running Windows-based applications that typically utilize full-size screens and rely on right-click inputs for full
functionality.
XenApp with Citrix Receiver offers a secure solution that allows mobile-device users access to all the functionality in their
Windows-based apps without the cost of rewriting those apps for native mobile platforms.
T he XenApp published apps delivery method utilizes HDX Mobile technology that solves the problems associated with
mobilizing Windows applications. T his method allows Windows applications to be refactored for a touch experience while
maintaining features such as multitouch gestures, native menu controls, camera, and GPS functions. Many touch features
are available natively in XenApp and XenDesktop and do not require any application source code changes to activate.
T hese features include:
Automatic display of the keyboard when an editable field has the focus
Larger picker control to replace Windows combo box control
Multitouch gestures, such as pinch and zoom
Inertia-sensed scrolling
T ouchpad or direct-cursor navigation
Upgrading physical machines is a daunting task many businesses face every three to five years, especially if the business
needs to maintain the most up-to-date operating systems and applications. Growing businesses also face daunting
overhead costs of adding new machines to their network.
T he VDI Personal vDisk delivery method provides fully personalized desktop operating systems to single users on any
machine or thin client using server resources. Administrators can create virtual machines whose resources — such as
processing, memory, and storage — are stored in the network’s data center.
T his can extend the life of older machines, keep software up to date, and minimize downtime during upgrades.
Network security is an ever-growing problem, especially when working with contractors, partners, and other third-party
contingent workers who need access to a company’s apps and data. T he workers may also need loaner laptops or other
devices, which cause additional cost concerns.
Data, applications, and desktops are stored behind the firewall of the secure network with XenDesktop and XenApp, so the
only thing the end user transmits is user-device inputs and outputs, such as keystrokes, mouse clicks, audio, and screen
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.52
updates. By maintaining these resources in a data center, XenDesktop and XenApp offer a more secure remote access
solution than using the typical SSL VPN.
With a VDI with Personal vDisk deployment, administrators can utilize thin clients or users’ personal devices by creating a
virtual machine on a network server and providing a single-user desktop operating system. T his allows IT to maintain
security with third-party workers without the need of purchasing expensive equipment.
When switching to a new operating system, IT can face the challenge of delivering legacy and incompatible applications.
With virtual-machine-hosted apps, users can run older applications through Citrix Receiver on the upgraded virtual machine
without any compatibility issues. T his allows IT additional time to resolve and test application compatibility issues, ease
users into the transition, and make help desk calls more efficient.
Additional benefit for using XenDesktop during migration include:
Reducing complexity for desktops
Improving IT ’s control
Enhancing end-user flexibility in terms of device usage and workspace location
Many design firms and manufacturing companies rely heavily on professional 3-D graphics applications. T hese companies
face financial strain from the costs of powerful hardware to support this type of software and also logistic problems that
come with the sharing of large design files via FT P, email, and similar ad hoc methods.
XenDesktop’s hosted physical desktop delivery method provides a single desktop image to workstations and blade servers
without the need of hypervisors to run graphic-intensive 3-D applications on a native operating system.
All files are saved in a central data center within the network, so sharing large design files to other users in the network is
faster and more secure because the files are not being transferred from one workstation to another.
Businesses that need large-scale call centers face the difficult challenge of maintaining adequate staffing for peak periods
while not overprovisioning machines during less busy hours.
T he Pooled VDI delivery method provides multiple users access to a standardized desktop dynamically at a minimal cost
when provisioning a large number of users. T he pooled machines are allocated on a per-session, first-come, first-served
basis.
T here is less day-to-day management of these virtual machines because any change made during the session is discarded
when the user logs off. T his also increases security.
T he XenApp hosted desktops delivery method is another viable option for transforming call centers. T his method hosts
multiple user desktops on a single server-based operating system.
T his is a more cost-efficient method than Pooled VDI, but with XenApp hosted desktops, users are restricted from installing
applications, changing system settings, and restarting the server.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.53
XenApp published apps and desktops
Nov 28 , 20 17
Use server OS machines to deliver XenApp published apps and published desktops.
Use case
You want inexpensive server-based delivery to minimize the cost of delivering applications to a large number of 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 may
include task workers such as call center operators and retail workers, or users that share workstations.
Application types: any application.
Benefit s and considerat ions
Manageable and scalable solution within your datacenter.
Most cost effective application delivery solution.
Hosted applications are managed centrally and users cannot modify the application, providing 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 to them.
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.
P rocess, host , and deliver applicat ions
Application processing takes place on hosting machines, rather than on the user devices. T he hosting machine can be a
physical or a virtual machine.
Applications and desktops reside on a server 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.
Server OS machines support Delivery Groups that host either desktops or applications, or both.
Session management and assignment
Server OS machines run multiple sessions from a single machine to deliver multiple applications 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 machine hosts. A second session on the same
machine is now unavailable. If both users request additional applications, no additional sessions are required because a
user can run multiple application 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.54
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.
To deliver XenApp published apps and desktops:
1. Install the applications you want to deliver on a master image running a supported Windows server OS.
2. Create a Machine Catalog for this master image or update an existing catalog with the master image.
3. Create a Delivery Group to deliver the applications and desktops to users. If you are delivering applications, select those
you want to deliver.
See the installation and configuration articles for details.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.55
VM hosted apps
Nov 28 , 20 17
Use Desktop OS machines to deliver VM hosted applications
Use Case
You want a client-based application delivery solution that is secure, provides centralized management, and supports a
large number of users per host server (or hypervisor), while providing users with applications 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 interact with the operation
system, such as Microsoft .NET framework. T hese types of applications are ideal for hosting on virtual machines.
Benefit s and considerat ions
Applications and desktops on the master image are securely managed, hosted, and run on machines within your
datacenter, providing a more cost effective application delivery solution.
On log on, users can be randomly assigned to a machine within a Delivery Group that is configured 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 desktop OS machines. T herefore, each user consumes a single machine
within a Delivery Group when they log on, and users must be online to access their applications.
T his method may increase the amount of server resources for processing applications and increase the amount of
storage for users' personal vDisks.
User experience
T he same seamless application experience as hosting shared applications on Server OS machines.
P rocess, host , and deliver applicat ions
T he same as server OS machines except they are virtual desktop OS machines.
Session management and assignment
Desktop OS machines run a single desktop session from a single machine. When accessing 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 selected based on session availability.
To deliver VM hosted apps:
1. Install the applications you want to deliver on a master image running a supported Windows desktop OS.
2. Create a Machine Catalog for this master image or update an existing catalog with the master image.
3. When defining the desktop experience for the machine catalog, decide whether you want users to connect to a new
VM each time they log in or connect to the same machine each time they log in.
4. Create a Delivery Group to deliver the application to users.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.56
5. From the list of application installed, select the application you want to deliver.
See the installation and configuration articles for details.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.57
VDI desktops
Nov 28 , 20 17
Use Desktop OS machines to deliver VDI desktops.
VDI desktops are hosted on virtual machines and provide each user with a desktop operating system.
VDI desktops require more resources than XenApp published desktops, but do not require that applications installed on
them support server-based operating systems. In additional, depending on the type of VDI desktop you choose, these
desktop can be assigned to individual users and allow these users a high degree of personalization.
When you create a Machine Catalog for VDI desktops, you create one of these types of desktops:
Random non-persistent desktops, also known as pooled VDI desktops. Each time users logs on to use one of these
desktops, they connect to a dynamically selected desktop in a pool of desktops based on a single master image. All
changes to the desktop are lost when the machine reboots.
Static non-persistent desktop. T he first time a user logs on the use one off these desktops, the user is assigned a
desktop from a pool of desktops based on a single master image. After the first use, each time a user logs in to use one
of these desktop, the user connects to the same desktop that user was assigned on first use. All changes to the
desktop are lost when the machine reboots.
Static persistent, also known as VDI with Personal vDisk. Unlike other types of VDI desktops, these desktops can be fully
personalized by users. T he first time a user logs on to use one of these desktops, the user is assigned a desktop from a
pool of desktops based on a single master image. Subsequent logons from that user connect to the same desktop that
was assigned on first use. Changes to the desktop are retained when the machine reboots because they are stored in a
Personal vDisk.
To deliver VDI desktops:
1. Create a master image running a supported Windows desktop OS.
2. Create a Machine Catalog for this master image or update an existing catalog with the master image. When defining the
desktop experience for the machine catalog, decide whether you want users to connect to a new VM each time they
log in, or connect to the same machine each time they log in. If users connect to the same machine, you can specify
how changes to the desktop are retained.
3. Create a Delivery Group to deliver the desktops to users.
See the installation and configuration articles for details.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.58
Network ports
Jan 30 , 20 18
T he following table lists the default network ports used by XenApp and XenDesktop Delivery Controllers, Windows VDAs,
Director, 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.
You may need this port information:
For regulatory compliance purposes.
If there is a network firewall between these components and other Citrix products or components, 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 documentation for the component for details.
For port information about other components such as StoreFront and Provisioning Services, see the component's
current "System requirements" article.
T he table lists 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 will require incoming ports for its own use. See the
Microsoft Windows documentation for details.
Component
Usage
P rot ocol
Def ault
Not es
incoming port s
VDA
ICA/HDX
TCP, UDP
1494
EDT protocol requires 1494 to
be open for UDP.
See ICA policy settings.
VDA
ICA/HDX with Session
TCP, UDP
2598
Reliability
EDT protocol requires 2598 to
be open for UDP.
See ICA policy settings.
VDA
ICA/HDX over T LS
TCP
443
All Citrix Receivers
VDA
Citrix DT LS Service
UDP
443
Only visible if T LS is configured
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.59
on the VDA.
VDA
ICA/HDX over WebSocket
TCP
8008
Citrix Receiver for HT ML5, and
Citrix Receiver for Chrome 1.6
and earlier only
VDA
ICA/HDX Audio over UDP
UDP
16500..16509
UDP
3224-3324
Real-time Transport
VDA
ICA/HDX Framehawk
Used by the Universal Print
VDA
ICA/Universal Print Server
TCP
7229
Server print data stream CGP
(Common Gateway Protocol)
listener.
Used by the Universal Print
VDA
ICA/Universal Print Server
TCP
8080
Server listener for incoming
HT T P/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 Controller
TCP
80
Delivery
VDA, StoreFront, Director,
TCP
80
Controller
Studio
Delivery
StoreFront, Director, Studio
TCP
443
Controller
over T LS
Delivery
Delivery Controller, VDA
TCP
89
Controller
Local Host Cache (T his use of
port 89 might change in future
releases.)
Delivery
Orchestration
TCP
9095
Orchestration
Controller
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.60
Director
Delivery Controller
TCP
80, 443
For Citrix Licensing:
Component
Usage
P rot ocol
Def ault
Notes
incoming
port s
License Server
License Server
TCP
27000
License Server
License Server for Citrix (vendor
TCP
7279
daemon)
License Server
License Administration Console
TCP
8082
License Server
Web Services for Licensing
TCP
8083
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.61
HDX
Dec 21, 20 17
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.
Citrix HDX includes a broad set of technologies that provide a high-definition user experience.
At t he 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 t he net work
HDX incorporates advanced optimization and acceleration capabilities to deliver the best performance over any network,
including low-bandwidth and high-latency WAN connections.
HDX features adapt to changes in the environment. T he features balance performance and bandwidth. T hey 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 t he dat a cent er
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. T his data includes client-side and serverside 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 decompresses the ICA traffic spread across various
virtual channels. Using the single virtual channel lessens complexity, enhances scalability, and is more cost effective.
Requirements:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.62
XenApp and XenDesktop 7.16
NetScaler version 12.0 Build 54.x
Citrix Receiver for Windows 4.10
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 enable, 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 capabilit ies f rom your virt ual deskt op:
See how Flash Redirection, one of three HDX multimedia redirection technologies, accelerates delivery of Adobe Flash
multimedia content:
1. Download Adobe Flash player (http://get.adobe.com/flashplayer/) and install it on both the virtual desktop and the
user device.
2. On the Desktop Viewer toolbar, select P ref erences . In the Desktop Viewer Preferences dialog box, select
the F lash tab and select Opt imize cont ent .
3. T o experience how Flash Redirection accelerates the delivery of Flash multimedia content to virtual desktops, view a
video on your desktop from a website containing Flash videos, such as YouT ube. Flash Redirection is seamless so that
users do not know when it is running. You can check to see whether Flash Redirection is being used. Look for a block
of color that appears momentarily before the Flash player starts, or by right-clicking on the video and looking for Flash
Redirection in the menu.
See how HDX delivers high definition audio:
1. Configure your Citrix client for maximum audio quality; see the Citrix Receiver documentation for details.
2. Play music files with a digital audio player (such as iT unes) on your desktop.
HDX provides a superior graphics and video experience for most users by default, and configuration isn't required. Citrix
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.63
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 multimedia redirection. Usually, adjustments to the multimedia redirection
feature policies aren't needed.
HDX delivers rich server-rendered video content to virtual desktops when multimedia redirection is not available: View a
video on a website containing high definition videos, such as http://www.microsoft.com/silverlight/iis-smoothstreaming/demo/.
Good to know:
For support and requirements information for HDX features, see the System requirements article. Except where
otherwise noted, HDX features are available for supported Windows Server OS and Windows Desktop OS machines, plus
Remote PC Access desktops.
T his content describes how to optimize the user experience further, improve server scalability, or reduce 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.
Limit at ion
When you're using Windows Media Player and Remote Audio & Video Extensions (RAVE) enabled inside a session, a black
screen might display if you right-click on the video content and select Always show Now P laying on t op .
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 configuration, session reliability starts and
then auto client reconnect follows.
Aut o 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:
Deskt ops. T he session window is grayed out and a countdown timer shows the time until the reconnections occur.
Applicat ions. T he session window closes and a dialog appears to the user containing a countdown 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. T he user can interact with the
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.64
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 reliabilit y
Session reliability reconnects ICA sessions seamlessly across network interruptions. Session reliability 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:
Deskt ops. T he session window becomes translucent and a countdown timer shows the time until the reconnections
occur.
Applicat ions. T he 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 actions 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 exchange of protocol. T he
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 transparency level: 80%
Session reliability connection: Enabled
Session reliability port number: 2598
For more information, see Session reliability policy settings.
Net Scaler wit h aut o client reconnect and session reliabilit y
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.
Continuum is a Windows 10 feature that adapts to the way the client device is used. T his version of Continuum support,
including dynamic change of modes, is available starting at VDA version 7.16 and Citrix Receiver for Windows version 4.10.
Windows 10 VDA detects the presence of a keyboard or mouse on a touch enabled client and puts the client in to desktop
mode. If a keyboard or mouse is not present, Windows 10 VDA puts the client in to tablet/mobile mode. T his detection
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.65
occurs on connection and reconnection. It also occurs at dynamic attachment or detachment of the keyboard or mouse.
T he feature is enabled by default. To disable this version of the feature, edit the Tablet mode toggle policy settings in the
ICA policy settings article.
For the feature version included in XenApp 7.14 and 7.15 LT SR and XenDesktop 7.14 and 7.15 LT SR, use the registry settings
to disable the feature. For more information, see Tablet mode for touch screen devices in the HDX article.
T he t ablet mode offers a user interface that is better suited to touch screens:
Slightly larger buttons.
T he Start screen and any apps you start open in a full screen.
T askbar contains a back button.
Icons removed from the task bar.
You have access to the File Explorer.
T he deskt op mode offers the traditional user interface where you interact in the same manner as using PC and a
keyboard and mouse.
Tablet mode requires a minimum of version XenServer 7.2. XenServer 7.2 integrates with the XenDesktop VDA, changing the
hypervisor to enable the virtual firmware settings for 2-in-1 devices. Windows 10 loads the GPIO driver on the target virtual
machine based on this updated BIOS. It is used for toggling between tablet and desktop modes within the virtual
machine. For more information, see http://docs.citrix.com/content/dam/docs/en-us/xenserver/currentrelease/downloads/xenserver-release-notes.pdf.
Citrix Receiver for HT ML5 (the light version) does not support Windows Continuum features.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.66
Run the XenServer CLI command to allow laptop/tablet switching:
xe vm-param-set uuid= <VM_UUID> plat f orm:acpi_lapt op_slat e= 1
Important
Updating the base image for an existing machine catalog after changing the metadata setting doesn't affect any previously
provisioned VMs. After making a change in the XenServer VM base image, create a catalog, choose the base image, and provision a
new Machine Creation Services (MCS) machine.
Bef ore st art ing a session
We recommend that you navigate to Set t ings >Syst em >T ablet Mode on the VDA before starting a session and set
the following options from the drop-down menus:
Use the appropriate mode for my hardware
Don’t ask me and always switch
If you don't set these options before starting the session, set the options after you start the session and restart the VDA.
T he 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). T he actual video quality using the default setting of medium depends on available
bandwidth.
T arget 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.
T he maximum supported frame rate per second is 60.
Display memory limit. Specifies the maximum video buffer size for the session in kilobytes (default = 65536 KB). For
connections requiring more color depth and higher resolution, increase the limit. You can calculate the maximum memory
required.
Several popular video conferencing applications are optimized for delivery from XenApp and XenDesktop through
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.67
multimedia redirection (see, for example, HDX RealT ime Optimization Pack). For applications that are not optimized, HDX
webcam video compression improves bandwidth efficiency and latency tolerance for webcams during video conferencing in
a session. T his technology streams webcam traffic over a dedicated multimedia virtual channel. T his technology uses less
bandwidth compared to the isochronous HDX Plug-n-Play USB redirection support, and works well over WAN connections.
Citrix Receiver 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 enabled 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 encoding by default. Hardware
encoding might consume more bandwidth than software encoding. To force software compression, add the following
DWORD key value to the registry key: HKCU\Software\Citrix\HdxRealT ime: DeepCompress_ForceSWEncode=1.
T he application on the server selects the webcam format and resolution based on the supported format types. When a
session starts, the client sends the webcam information to the server. Choose a webcam from the application. When the
webcam and the application support high definition rendering, the application uses high definition resolution. We support
webcam resolutions up to 1920x1080.
T his feature requires the Citrix Receiver for Windows, minimum version 4.10.
You can use a registry key to disable the feature. T he default resolution of 352x288 is used:
HKEY_CURRENT _USER\Software\Citrix\HDXRealT ime
Name: Disable_HighDefWebcam
Type: REG_DWORD
Data: 0 = Disable the high definition webcam streaming
You can use registry keys on the client to configure a specific resolution. Ensure that the camera supports the specified
resolution:
HKEY_CURRENT _USER\Software\Citrix\HDXRealT ime
Name: DefaultWidth
Type: REG_DWORD
Data (decimal): desired width (for example 1280)
Name: DefaultHeight
Type: REG_DWORD
Data (decimal): desired height (for example 720)
Priorities are assigned to network traffic across multiple connections for a session using Quality of Service (QoS)-supported
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.68
routers. Four TCP streams (real time, interactive, background, and bulk) and two User Datagram Protocol (UDP) streams
(voice and Framehawk display remoting) are available to carry ICA traffic between the user device and the server. Each
virtual channel is associated with a specific priority and transported in the corresponding connection. You can set the
channels independently, based on the TCP port number used for the connection.
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 (QoS) is supported only when multiple session reliability ports, or the CGP ports, are configured.
Caut ion: Use transport security when using this feature. Citrix recommends using Internet Protocol Security (IPsec) or
Transport Layer Security (T LS). T LS connections are supported only when the connections traverse a NetScaler Gateway
that supports multi-stream ICA. On an internal corporate network, multi-stream connections with T LS are not supported.
To set Quality of Service for multiple streaming connections, add the following Citrix policy settings to a policy (see Multistream connections policy settings for details):
Multi-Port policy - T his 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.
T ype more CGP ports in CGP port1, CGP port2, and CGP port3 as needed, and identify priorities 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 - T his setting is disabled by default. If you use Citrix NetScaler SD-WAN with MultiStream support in your environment, you do not need to configure this setting. Configure this policy setting when using
third-party routers or legacy Branch Repeaters to achieve the desired Quality of Service (QoS).
Multi-Stream user setting - T his setting is disabled by default.
For policies containing these settings to take effect, users must log off and then log on to the network.
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.
Under HKEY_LOCAL_MACHINE/SOFT WARE/Citrix, create the CtxKlMap key.
Set the DWORD value of EnableKlMap = 1
To disable this feature, set the DWORD value EnableKlMap = 0 or delete the CtxKlMap key.
Enable Unicode keyboard layout mapping compat ible mode
By default, Unicode keyboard layout mapping automatically hooks some windows API to reload the new Unicode keyboard
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.69
layout map when you change the keyboard layout on the server side. A few applications cannot be hooked. To keep
compatibility, you can change the feature to compatible mode to support these non-hooked applications.
1. Under the HKEY_LOCAL_MACHINE/SOFT WARE/Citrix/CtxKlMap key, set the DWORD value DisableWindowHook =1.
2. T o use normal Unicode keyboard layout mapping, set DWORD value DisableWindowHook = 0.
Related information
Graphics
Multimedia
General content redirection
Adaptive transport
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.70
Adaptive transport
Dec 22, 20 17
Adaptive transport is a data transport mechanism for XenApp and XenDesktop. It is faster, more scalable, improves
application interactivity, and is more interactive on challenging long-haul WAN and internet connections. Adaptive transport
maintains high server scalability and efficient use of bandwidth. By using adaptive transport, ICA virtual channels
automatically respond to changing network conditions. T hey intelligently switch the underlying protocol between the Citrix
protocol called Enlightened Data Transport (EDT ) and TCP to deliver the best performance. It improves data throughput for
all ICA virtual channels including T hinwire display remoting, file transfer (Client Drive Mapping), printing, and multimedia
redirection. T he same setting is applicable for both LAN and WAN conditions.
When set to P ref erred , data transport over EDT is used as primary and fallback to TCP. With the Citrix Receiver for
Windows minimum version 4.10 and session reliability enabled, EDT and TCP are attempted in parallel during the initial
connection, session reliability reconnection, and auto client reconnect. Doing so reduces connection time if EDT is
P ref erred , but the required underlying UDP transport is unavailable and TCP must be used. By default, after fallback to TCP,
adaptive transport continues to seek EDT every five minutes.
Important
EDT and TCP in parallel require:
Citrix Receiver for Windows minimum version 4.10 and Session Reliability.
Citrix Receiver for Mac minimum version 12.8 and Session Reliability.
By default, adaptive transport is enabled (P ref erred ), and EDT is used when possible, with fallback to TCP.
For testing purposes, you can set Diagnost ic mode , in which case only EDT is used, and fallback to TCP is disabled.
XenApp and XenDesktop: Minimum version 7.16
VDA for Desktop OS: Minimum version 7.13
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.71
VDA for Server OS: Minimum version 7.13
StoreFront: Minimum version 3.9
Citrix Receiver for Windows: Minimum version 4.7 (EDT and T CP in parallel require minimum version 4.10 and Session
Reliability)
Citrix Receiver for Mac: Minimum version 12.5 (EDT and T CP in parallel require minimum version 12.8 and Session Reliability)
Citrix Receiver for iOS: Minimum version 7.2
Citrix Receiver for Linux: Version 13.6 for Direct VDA Connections only and 13.7 for DT LS support using NetScaler
Gateway (or DT LS for direct VDA connections).
Citrix Receiver for Android: Version 3.12.3 for Direct VDA Connections only
IPv4 VDAs only. IPv6 and mixed IPv6 and IPv4 configurations are not supported.
NetScaler: Minimum versions 11.1 build 51.21, 12.0 build 35.6. We recommend minimum versions 11.1 build 55.10 or
12.0 Build 53.6 as these versions include important DT LS fragmentation fixes. For more information on NetScaler
configuration, see Configuring NetScaler Gateway to support Advanced T ransport.
1. Install XenApp and XenDesktop.
2. Install StoreFront. If you are using NetScaler Gateway, verify Session Reliability is enabled in Studio > Storefront >
Manage NetScaler Gateway > Select your NetScaler > Secure T icket Authority > "Enable Session Reliability".
3. Install the VDA (for Desktop OS or Server OS).
4. Install Citrix Receiver for Windows, Citrix Receiver for Mac, Citrix Receiver for iOS, Citrix Receiver for Android, or Citrix
Receiver for Linux.
5. If you are using NetScaler Gateway, make sure that Session Reliability is enabled in the Studio policy, and that DT LS is
enabled in the front-end VPN vServer.
6. In Studio, enable the policy setting, HDX Adaptive T ransport (it is enabled by default). We also recommend that you do
not enable this feature as a universal policy for all objects in the Site.
T o enable the policy setting, set the value to Preferred, then click OK.
P ref erred. Adaptive transport over EDT is used when possible, with fallback to T CP.
Diagnost ic mode. EDT is forced on and falls back to T CP is disabled. We recommend this setting only for
troubleshooting.
Of f . T CP is forced on, and EDT is disabled.
7. Click Next, and complete the steps in the wizard.
8. T he policy takes effect when the user reconnects the ICA session. T hough not required, you can run gpupdat e /f orce
to pull the policy setting to the server, but the user still has to reconnect the ICA session.
9. Start a session from a supported Citrix Receiver to establish a connection using adaptive transport.
10. For secure external access, configure DT LS encryption on NetScaler Unified Gateway. For more information, see
Configuring NetScaler Gateway to support Advanced T ransport.
To confirm that the policy setting has taken effect:
Check that the ICA User Datagram Protocol (UDP) services are enabled on a VDA using net st at -a .
Check that the virtual channels are running over EDT using Direct or or the Ct xSession.exe command-line utility
available on the VDA.
Direct or example
In Director, Session Det ails > Connect ion T ype displays the policy settings. Look for Connection type HDX . If the
protocol is UDP , EDT is active for the session. If the protocol is T CP , the session is in fallback or default mode. If the
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.72
Connection type is RDP , ICA is not in use and the protocol is n/a . For more information, see Monitor sessions.
Ct xSession.exe example
T his example illustrates that EDT over UDP is active for the session. Type CtxSession.exe in the command line.
C:\Program Files (x86)\Citrix\System32>CtxSession
Session 2 Transport Protocols: UDP -> CGP -> ICA
To see verbose statistics, use the -v switch:
>CtxSession -v
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.73
Install and configure
Nov 28 , 20 17
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 XenApp or XenDesktop.
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, Citrix License Server, and 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 Desktop 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 contains complete information about the available VDA installers.)
Install other optional components
If you plan to use the Citrix Universal Print Server, install its server component on your print servers. See Install core
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.74
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. For details, see the
Self-Service Password Reset documentation.
Optionally, integrate more Citrix components into your XenApp or XenDesktop deployment.
Provisioning Services is an optional component of XenApp and XenDesktop that provisions machines by streaming a
master image to target devices.
Citrix NetScaler Gateway is a secure application access solution that provides administrators with granular applicationlevel policy and action controls to secure access to applications and data.
Citrix NetScaler SD-WAN is a set of appliances that optimize WAN performance.
For installation guidance, see the documentation for these components, features, and technologies.
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 master image. When using
a hypervisor or cloud service to provide VMs, you first create a master image on that host. T hen, 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 Application Groups for
applications that are shared across different Delivery Groups or used by a subset of users within Delivery Groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.75
Prepare to install
Nov 30 , 20 17
Deploying XenApp and XenDesktop begins with installing the following components. T his process prepares for delivery of
applications and desktops to users inside your firewall.
One or more Delivery Controllers
Citrix Studio
Citrix Director
Citrix StoreFront
Citrix License Server
One or more Citrix Virtual Delivery Agents (VDAs)
Optional components and technologies such as the Universal Print Server, the Federated Authentication Service, and
Self-Service Password Reset
For users outside your firewall, install and configure an additional component, such as NetScaler. For an introduction to
using NetScaler with StoreFront, see Integrate XenApp and XenDesktop with NetScaler Gateway.
How you can inst all component s
You can use the full-product installer on the XenApp and XenDesktop ISO to deploy many components and technologies.
You can use a standalone VDA installer to install VDAs. All installers offer graphical and command line interfaces. See
Installers.
T he product ISO contains sample scripts that install, upgrade, or remove VDAs for machines in Active Directory. You
can also use the scripts to manage master images used by Machine Creation Services (MCS) and Provisioning Services
(PVS). For details, see Install VDAs using scripts.
As an automated alternative to using the installers, Citrix Smart Tools uses blueprints to create a XenApp and XenDesktop
deployment. For details, see Smart Tools product documentation.
Information to review before installation
T echnical overview: If you're unfamiliar with the product and its components.
Changes in 7.x: If you are moving from a XenApp 6.x or XenDesktop 5.6 deployment to the current version.
Security: When planning your deployment environment.
Known issues: Issues you might encounter in this version.
Databases: Learn about the system databases and how to configure them. During Controller installation, you can install
SQL Server Express for use as the Site database. You configure most database information when you create a Site,
after you install the core components.
Remote PC Access: If you're deploying an environment that enables your users to access their physical machines in the
office remotely.
Connections and resources: If you're using a hypervisor or cloud service to host or provision VMs for applications and
desktops. You can configure the first connection when you create a Site (after you install the core components). Set up
your virtualization environment any time before then.
Microsoft System Center Configuration Manager: If you're using ConfigMgr to manage access to applications and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.76
desktops, or if you're using the Wake on LAN feature with Remote PC Access.
Where to install components
Review the System requirements for supported platforms, operating systems, and versions. Component prerequisites are
installed automatically, except as noted. See the Citrix StoreFront and the Citrix License Server documentation for their
supported platforms and prerequisites.
You can install the core components on the same server or on different servers.
Installing all the core components on one server can work for evaluation, test, or small production deployments.
T o accommodate future expansion, consider installing components on different servers. For example, installing Studio on
a different machine than the server where you installed the Controller allows you to manage the site remotely.
For most production deployments, installing core components on separate servers is recommended.
You can install both a Delivery Controller and a VDA for Server OS on the same server. Launch the installer and select the
Delivery Controller (plus any other core components you want on that machine). T hen launch the installer again and select
the Virtual Delivery Agent for Server OS.
Ensure that each operating system has the latest updates. For example, installation of a Controller or VDA on Windows
Server 2012 R2 fails if Windows update KB2919355 is not installed.
Ensure that all machines have synchronized system clocks. T he Kerberos infrastructure that secures communication
between the machines requires synchronization.
Optimization guidance for Windows 10 machines is available in CT X216252.
Where NOT to install components:
Do not install any components on an Active Directory domain controller.
Installing a Controller on a node in a SQL Server clustering installation, SQL Server mirroring installation, or on a server
running Hyper-V is not supported.
Do not install Studio on a server running XenApp 6.5 Feature Pack 2 for Windows Server 2008 R2 or any earlier version of
XenApp.
If you attempt to install (or upgrade to) a Windows VDA on an OS that is not supported for this XenApp and XenDesktop
version, a message guides you to a CT X article that describes your options.
Permission and Active Directory requirements
You must be a domain user and a local administrator on the machines where you are installing components.
To use the standalone VDA installer, you must have elevated administrative privileges or use Run as administ rat or.
Configure your Active Directory domain before starting an installation.
System requirements lists the supported Active Directory functional levels. Active Directory contains more information.
You must have at least one domain controller running Active Directory Domain Services.
Do not install any XenApp or XenDesktop components on a domain controller.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.77
Do not use a forward slash (/) when specifying Organizational Unit names in Studio.
T he 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 instructions
Installation guidance, considerations, and best
practice
During inst allat ion:
Usually, if a component has prerequisites, the installer deploys them if they are not present. Some prerequisites might
require a machine restart.
When you create objects before, during, and after installation, specify unique names for each object. For example, provide
unique names for networks, groups, catalogs, and resources.
If a component does not install successfully, the installation stops with an error message. Components that installed
successfully are retained. You do not need to reinstall them.
Citrix analytics are collected automatically when you install (or upgrade) components. By default, that data is uploaded to
Citrix automatically when the installation completes. Also, when you install components, you are automatically enrolled in
the Citrix Customer Experience Improvement Program (CEIP), which uploads anonymous data. During installation, you can
also choose to participate in other Citrix technologies (such as Smart Tools) that collect diagnostics for maintenance and
troubleshooting. For information about these programs, see Citrix Insight Services.
Google Analytics are collected (and later uploaded) automatically when you install (or upgrade) Studio. After installing
Studio, you can change this setting with the registry key HKLM\Software\Citrix\DesktopStudio\GAEnabled. A value of 1
enables collection and upload, 0 disables collection and upload.
If a VDA installation fails, an MSI analyzer parses the failing MSI log, displaying the exact error code. T he analyzer suggests
a CT X article, if it's a known issue. T he analyzer also collects anonymized data about the failure error code. T his 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 inst allat ion:
T he Citrix Receiver for Windows is included by default when you install a VDA, except when using the
VDAWorkstationCoreSetup.exe installer. You can exclude the Citrix Receiver from the installation. You or your users can
download and install (and upgrade) Citrix Receiver and other Citrix Receivers from the Citrix website. Alternatively, you can
make those Citrix Receivers available from your StoreFront server. See Make Citrix Receiver installation files available on the
server, or the equivalent content in the StoreFront version you're using.
T he Print Spooler Service is enabled by default on supported Windows servers. If you disable this service, you cannot
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.78
successfully install a VDA for Windows Server OS, so ensure that this service is enabled before installing a VDA.
Most supported Windows editions come with Microsoft Media Foundation already installed. If the machine on which
you're installing a VDA does not have Media Foundation (such as N editions), several multimedia features will not be
installed and will not work. You can acknowledge the limitation, or end the VDA installation and restart it later, after
installing Media Foundation. In the graphical interface, this choice is presented in a message. In the command line, you can
use the /no_mediafoundation_ack to acknowledge the limitation.
If Media Foundation is not present on the machine with the VDA, these multimedia features do not work:
Flash Redirection
Windows Media Redirection
HT ML5 Video Redirection
HDX Realtime Webcam Redirection
When you install the VDA, a new local user group called Direct Access Users is created automatically. On a VDA for Desktop
OS, this group applies only to RDP connections. On a VDA for Server OS, this group applies to ICA and RDP connections.
T he VDA must have valid Controller addresses with which to communicate. Otherwise, sessions cannot be established. You
can specify Controller addresses when you install the VDA or later. Just remember that it must be done.
After installing a VDA on a Windows Server 2012 R2 system, use the Kerberos Enable Tool (XASsonKerb.exe) to ensure the
correct operation of Citrix Kerberos authentication. T he tool is in the Support > Tools > XASsonKerb folder on the
installation media. You must have local administrator privileges to use the tool. Run xassonkerb.exe -install from a command
prompt on the server. If you later apply an update that changes the registry location
HKLM\System\CurrentControlSet\Control\LSA\OSConfig, run the command again. To see all available tool options, run the
command with the -help parameter.
Rest art s af t er and during VDA inst allat ion:
A restart is required at the end of the VDA installation. T hat restart occurs automatically by default.
To minimize the number of restarts needed during VDA installation:
Ensure that a supported .NET Framework version is installed before beginning the VDA installation.
For Windows Server OS machines, install and enable the RDS role services before installing the VDA.
If you do not install those prerequisites before installing the VDA:
If you are using the graphical interface or the command line interface without the /noreboot option, the machine
restarts automatically after installing the prerequisite.
If you are using the command line interface with the /noreboot option, you must initiate the restart.
After each restart, run the installer or command again to continue the VDA installation.
Installers
Using the full-product installer provided in the XenApp and XenDesktop ISO, you can:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.79
Install, upgrade, or remove core XenApp and XenDesktop components: Delivery Controller, Studio, Director, StoreFront,
License Server
Install or upgrade Windows VDAs for server or desktop operating systems
Install the Universal Print Server UpsServer component on your print servers
Install the Federated Authentication Service
Install the Self-Service Password Reset Service
To deliver a desktop from a Server 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 are available on the Citrix download pages. T he standalone VDA installers are much smaller than
the full-product ISO. T hey 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.
T hree standalone VDA installers are available for download.
VDAServerSetup.exe:
Installs a VDA for Server OS. It supports all the VDA for Server OS options that are available with the full-product installer.
VDAWorkstationSetup.exe:
Installs a VDA for Desktop OS. It supports all the VDA for Desktop OS options that are available with the full-product
installer.
VDAWorkstationCoreSetup.exe:
Installs a VDA for Desktop 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. T herefore, it supports only a subset of the options that
are valid with the full-product or VDAWorkstationSetup installers.
T his installer does not install or contain the components used for:
App-V.
Profile management. Excluding Citrix Profile management from the installation affects Citrix Director displays. For details,
see Install VDAs.
Machine Identity Service.
Personal vDisk or AppDisks.
Citrix PDF Printer Driver.
T he VDAWorkstationCoreSetup.exe installer does not install or contain a Citrix Receiver for Windows.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.80
Using VDAWorkstationCoreSetup.exe is equivalent to using the full-product or VDAWorkstationSetup installer to install a
Desktop OS VDA and either:
In the graphical interface: Selecting the Remote PC Access option on the Environment page and clearing the Citrix
Receiver check box on the Component s page.
In the command line interface: Specifying the /remotepc and /components vda options.
In the command line interface: Specifying /components vda and /exclude "Citrix Personalization for App-V - VDA"
"Personal vDisk" "Machine Identity Service" "Citrix User Profile Manager" "Citrix User Profile Manager WMI Plugin" "Citrix
PDF Printer Driver".
You can install the omitted components/features later by running the full-product installer. T hat action installs all missing
components.
Citrix installation return codes
T he installation log contains the result of component installations as a Citrix return code, not a Microsoft value.
0 = Success
1 = Failed
2 = PartialSuccess
3 = PartialSuccessAndRebootNeeded
4 = FailureAndRebootNeeded
5 = UserCanceled
6 = MissingCommandLineArgument
7 = NewerVersionFound
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. T his 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 completely 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 a CMD scripts (which return Microsoft exit codes) or change the success
codes in your Configuration Manager package.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.81
Microsoft Azure Resource Manager virtualization
environments
Nov 28 , 20 17
Follow this guidance when using Microsoft Azure Resource Manager to provision virtual machines in your XenApp or
XenDesktop deployment.
You can configure XenApp or XenDesktop to provision resources in Azure Resource Manager either when you create the
XenApp or XenDesktop Site (which includes creating a connection), or when you create a host connection later (after
creating the Site).
You should be familiar with the following:
Azure Active Directory: https://azure.microsoft.com/en-us/documentation/articles/active-directory-howto-tenant/
Consent framework: https://azure.microsoft.com/en-us/documentation/articles/active-directory-integratingapplications/
Service principal: https://azure.microsoft.com/en-us/documentation/articles/active-directory-application-objects/
Azure Disk Encryption is not supported when using Machine Creation Services.
Azure on-demand provisioning
When you use MCS to create machine catalogs in Azure Resource Manager, the Azure on-demand provisioning feature:
Reduces your storage costs
Provides faster catalog creation
Provides faster virtual machine (VM) power operations
For the administrator, on-demand provisioning introduces no differences in the Studio procedures for creating host
connections and MCS machine catalogs. T he differences lie in how and when resources are created and managed in Azure,
and VM visibility in the Azure portal.
Before Azure on-demand provisioning was used with XenApp and XenDesktop, when MCS created a catalog, the VMs were
created in Azure during the provisioning process.
With Azure on-demand provisioning, VMs are created only when XenApp and XenDesktop initiates a power-on action, after
the provisioning completes. A VM is visible in the Azure portal only when it is running. (In Studio, VMs are visible, whether or
not they're running.)
When you create an MCS catalog, the Azure portal displays the resource groups, network security group, storage accounts,
network interfaces, base images, and identity disks. T he Azure portal does not show a VM until XenApp and XenDesktop
initiates a power-on action for it. (At that time, the VM's status in Studio changes to On.)
For a pooled machine, the operating system disk and write back cache exist only when the VM exists. T his can result in
significant storage savings if you routinely shut down machines (for example, outside of working hours).
For a dedicated machine, the operating system disk is created the first time the VM is powered on. It remains in storage
until the machine is deleted.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.82
When XenApp and XenDesktop initiates a power-off action for a VM, that VM is deleted in Azure and it no longer appears
in the Azure portal. (In Studio, the VM's status changes to Off.)
Cat alogs creat ed bef ore on-demand provisioning
If you have machine catalogs that were created before XenApp and XenDesktop supported the Azure on-demand
provisioning feature (mid-2017), VMs in those catalogs are visible in the Azure portal whether or not they're running. You
cannot convert those VMs to on-demand machines.
To take advantage of the performance enhancements and storage cost benefits of on-demand provisioning, create new
catalogs using MCS.
Create a connection to Azure Resource Manager
T he Connections and resources article contains information about the wizards that create a connection. T he following
information covers details specific to Azure Resource Manager connections.
Considerations:
Service principals must have been granted contributor role for the subscription.
When creating the first connection, Azure prompts you to grant it the necessary permissions. For future connections
you must still authenticate, but Azure remembers your previous consent and does not display the prompt again.
Accounts used for authentication must be a co-administrator of the subscription.
T he account used for authentication must be a member of the subscription’s directory. T here are two types of
accounts to be aware of: ‘Work or School’ and ‘personal Microsoft account.’ See CT X219211 for details.
While you can use an existing Microsoft account by adding it as a member of the subscription’s directory, there can be
complications if the user was previously granted guest access to one of the directory’s resources. In this case, they may
have a placeholder entry in the directory that does not grant them the necessary permissions, and an error is returned.
One way to rectify this is to remove the resources from the directory and add them back explicitly. However, exercise
this option carefully, because it may have unintended effects for other resources that account can access.
T here is a known issue where certain accounts are detected as directory guests when they are actually members. T his
typically occurs with older established directory accounts. Workaround: add a new account to the directory, which will
take the proper membership value.
Resource groups are simply containers for resources, and they may contain resources from regions other than their own
region. T his can potentially be confusing if you expect all of the resources displayed in a resource group's region to be
available.
Ensure your network and subnet are large enough to host the number of machines you require. T his may require some
foresight, but Microsoft helps you specify the right values, with guidance about the address space capacity.
T here are two ways to establish a host connection to Azure Resource Manager:
Authenticate to Azure Resource Manager to create a new service principal.
Use the details from a previously-created service principal to connect to Azure Resource Manager.
Before you start, make sure:
You have a user account in your subscription's Azure Active Directory tenant.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.83
T he Azure AD user account is also a co-administrator for the Azure subscription you want to use for provisioning
resources.
In the Site Setup or Add Connection and Resources wizard:
1. On the Connect ion page, select the Microsof t Azure connection type and your Azure environment.
2. On the Connect ion Det ails page, enter your Azure subscription ID and a name for the connection. T he connection
name can contain 1-64 characters, and cannot contain only blank spaces or the characters \/;:#.*?=<>|[]{}"'()'). After you
enter the subscription ID and connection name, the Creat e new button is enabled.
3. Enter the Azure Active Directory account user name and password.
4. Click Sign in .
5. Click Accept to give XenApp or XenDesktop the listed permissions. XenApp or XenDesktop creates a service principal
that allows it to manage Azure Resource Manager resources on behalf of the specified user.
6. After you click Accept , you are returned to the Connect ion page in Studio. Notice that when you successfully
authenticate to Azure, the Creat e new and Use exist ing buttons are replaced with Connect ed , and a green check
mark indicates the successful connection to your Azure subscription.
7. Indicate which tools to use to create the virtual machines, and then click Next . (You cannot progress beyond this page
in the wizard until you successfully authenticate with Azure and accept giving the required permissions.
Resources comprise the region and the network.
On the Region page, select a region.
On the Net work page,
T ype a 1-64 character resources name to help identify the region and network combination in Studio. A resource
name cannot contain only blank spaces, and cannot contain the characters \/;:#.*?=<>|[]{}"'()'.
Select a virtual network and resource group pair. (Since you can have more than one virtual network with the same
name, pairing the network name with the resource group provides unique combinations.) If you selected a region on
the previous page that does not have any virtual networks, you will need to return to that page and select a region
that has virtual networks.
Complete the wizard.
To create a service principal manually, connect to your Azure Resource Manager subscription and use the PowerShell
cmdlets provided below.
Prerequisites:
$SubscriptionId: Azure Resource Manager SubscriptionID for the subscription where you want to provision VDAs.
$AADUser: Azure AD user account for your subscription’s AD tenant.
Make the $AADUser the co-administrator for your subscription.
$ApplicationName: Name for the application to be created in Azure AD.
$ApplicationPassword: Password for the application. You will use this password as the application secret when creating
the host connection.
To create a service principal:
Step 1: Connect to your Azure Resource Manager subscription.
Login-AzureRmAccount.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.84
Step 2: Select the Azure Resource Manager subscription where you want to create the service principal.
Select-AzureRmSubscription -SubscriptionID $SubscriptionId;
Step 3: Create the application in your AD tenant.
$AzureADApplication = New-AzureRmADApplication -DisplayName $ApplicationName -HomePage
"https://localhost/$ApplicationName" -IdentifierUris https://$ApplicationName -Password $ApplicationPassword
Step 4: Create a service principal.
New-AzureRmADServicePrincipal -ApplicationId $AzureADApplication.ApplicationId
Step 5: Assign a role to the service principal.
New-AzureRmRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName
$AzureADApplication.ApplicationId – scope /subscriptions/$SubscriptionId
Step 6: From the output window of the PowerShell console, note the ApplicationId. You will provide that ID when creating
the host connection.
In the Site Setup or Add Connection and Resources wizard:
1. On the Connect ion page, select the Microsof t Azure connection type and your Azure environment.
2. On the Connect ion Det ails page, enter your Azure subscription ID and a name for the connection. (T he connection
name can contain 1-64 characters, and cannot contain only blank spaces or the characters \/;:#.*?=<>|[]{}"'()').
3. Click Use exist ing . Provide the subscription ID, subscription name, authentication URL, management URL, storage suffix,
Active Directory ID or tenant ID, application ID, and application secret for the existing service principal. After you enter
the details, the OK button is enabled. Click OK .
4. Indicate which tools to use to create the virtual machines, and then click Next . T he service principal details you provided
will be used to connect to your Azure subscription. (You cannot progress beyond this page in the wizard until you provide
valid details for the Use existing option.)
Resources comprise the region and the network.
On the Region page, select a region.
On the Net work page:
T ype a 1-64 character resources name to help identify the region and network combination in Studio. A resource
name cannot contain only blank spaces, and cannot contain the characters \/;:#.*?=<>|[]{}"'()'.
Select a virtual network and resource group pair. (Since you can have more than one virtual network with the same
name, pairing the network name with the resource group provides unique combinations.) If you selected a region on
the previous page that does not have any virtual networks, you will need to return to that page and select a region
that has virtual networks.
Complete the wizard.
Create a Machine Catalog using an Azure Resource
Manager master image
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.85
T his information is a supplement to the guidance in the Create Machine Catalogs article.
A master image is the template that will be used to create the VMs in a Machine Catalog. Before creating the Machine
Catalog, create a master image in Azure Resource Manager. For information about master images in general, see the Create
Machine Catalogs article.
When you create a Machine Catalog in Studio:
T he Operat ing Syst em and Machine Management pages do not contain Azure-specific information. Follow the
guidance in the Create Machine Catalogs article.
On the Mast er Image page, select a resource group and then navigate (drill down) through the containers to the Azure
VHD you want to use as the master image. T he VHD must have a Citrix VDA installed on it. If the VHD is attached to a
VM, the VM must be stopped.
T he St orage and License T ypes page appears only when using an Azure Resource Manager master image.
Select a storage type: standard or premium. T he storage type affects which machine sizes are offered on the Virtual
Machines page of the wizard. Both storage types make multiple synchronous copies of your data within a single data
center. For details about Azure storage types and storage replication, see the following:
https://azure.microsoft.com/en-us/documentation/articles/storage-introduction/
https://azure.microsoft.com/en-us/documentation/articles/storage-premium-storage/
https://azure.microsoft.com/en-us/documentation/articles/storage-redundancy/
Select whether or not to use existing on-premises Windows Server licenses. Doing so in conjunction with using
existing on-premises Windows Server images utilizes Azure Hybrid Use Benefits (HUB). More details are available at
https://azure.microsoft.com/pricing/hybrid-use-benefit/
HUB reduces the cost of running VMs in Azure to the base compute rate since it waives the price of additional
Windows Server licenses from the Azure gallery. You need to bring your on-premises Windows Servers images to Azure
to use HUB. Azure gallery images are not supported. On-premises Windows Client licenses are currently not supported.
See https://blogs.msdn.microsoft.com/azureedu/2016/04/13/how-can-i-use-the-hybrid-use-benefit-inazure/%23comment-145
To check if the provisioned Virtual Machines are successfully utilizing HUB, run the PowerShell command
Get-AzureRmVM -ResourceGroup MyResourceGroup -Name MyVM
and check that the license type is Windows_Server. Additional instructions are available at
https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-windows-hybrid-use-benefit-licensing/
On the Virt ual Machines page, indicate how many VMs you want to create; you must specify at least one. Select a
machine size. After you create a Machine Catalog, you cannot change the machine size. If you later want a different
size, delete the catalog and then create a new catalog that uses the same master image and specifies the desired
machine size.
Virtual machine names cannot contain non-ASCII or special characters.
(When using MCS) On the Resource Groups page, choose whether to create new resource groups or use existing
groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.86
If you choose to create new resource groups, click Next .
If you choose to use existing resource groups, select groups from the Available P rovisioning Resource Groups list.
Remember: Select enough groups to accommodate the machines you're creating in the catalog. Studio displays a
message if you choose too few. You might want to select more than the minimum required if you plan to add more
VMs to the catalog later. You can't add more resource groups to a catalog after the catalog is created.
For more information, see the Azure resource groups section later in this article.
T he Net work Cards , Comput er Account s , and Summary pages do not contain Azure-specific information. Follow
the guidance in the Create Machine Catalogs article.
Complete the wizard.
Azure resource groups
Azure provisioning resource groups provide a way to provision the VMs that provide applications and desktops to users. You
can add existing empty Azure resource groups when you create an MCS machine catalog in Studio, or have new resource
groups created for you.
For information about Azure resource groups, see Azure Resource Manager Overview.
Each resource group can hold up to 240 VMs. T here must be sufficient available empty resource groups in the region
where you're creating the catalog. If you want to use existing resource groups when you create a machine catalog, you
must select enough available groups to accommodate the number of machines that will be created in the catalog. For
example, if you specify 500 machines in the catalog creation wizard, select at least three available provisioning resource
groups.
You cannot add resource groups to a machine catalog after the catalog is created. So, consider adding enough
resource groups to accommodate machines you might add to the catalog later.
Create empty resource groups in the same region as your host connection.
If you want the XenApp and XenDesktop Service to create new resource groups for each MCS catalog, the Azure
service principal associated with the host connection must have permission to create and delete resource groups. If you
want the XenApp and XenDesktop Service to use existing empty resource groups, the Azure service principal associated
with the host connection must have Contributor permission on those empty resource groups.
When you create a host connection in Studio using the Creat e new option, the created service principal has
subscription scope contribute permissions. Alternatively, you can use the Use exist ing option to create the connection,
and provide the details of an existing subscription scope service principal. If you use the Creat e new option and create
the Service Principal in Studio, it has the needed permissions to create and delete new resource groups or provision into
existing empty resource groups.
Narrow scope service principals must be created using PowerShell. Additionally, when using a narrow scope service
principal, you must use PowerShell or the Azure portal to create empty resource groups for each catalog where MCS will
provision VMs. For instructions, see the blog post https://www.citrix.com/blogs/2016/11/09/azure-role-based-accesscontrol-in-xenapp-xendesktop/.)
If you are using narrow scope service principal for the host connection and don't see your master image resource
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.87
group on the Mast er Image page of the catalog creation wizard, it is probably because the narrow scope service
principal you are using doesn't have the permission "Microsoft.Resources/subscriptions/resourceGroups/read" to list
the master image resource group. Close the wizard, update the service principal with the permission (see the blog post
for instructions), and then restart the wizard. (T he update in Azure can take up to 10 minutes to appear in Studio.)
T he Resource Groups page in the catalog creation wizard allows you to choose whether to create new resource groups or
use existing groups. See the section earlier in this article: Create a machine catalog using an Azure Resource Manager
master image.
What happens t o resource groups when you delet e a machine cat alog
If you let the XenApp and XenDesktop Service create new resource groups when you create the machine catalog, and
then later delete the catalog, those resource groups and all of the resources in those resource groups are also deleted.
If you use existing resource groups when you create the machine catalog, and then later delete the catalog, all resources in
those resource groups are deleted, but the resource groups are not deleted.
When you use existing resource groups, the list of available resource groups on the Resource Groups page in the catalog
creation wizard does not auto-refresh. So, if you have that wizard page open and create or add permissions to resource
groups in Azure, the changes are not reflected in the wizard's list. To see the latest changes, either go back to the Machine
Management page in the wizard and reselect the resources associated with the host connection, or close and restart the
wizard. It can take up to 10 minutes for changes made in Azure to appear in Studio.
A resource group should be used in only one machine catalog. However, this is not enforced. For example, you select 10
resource groups when creating a catalog, but create only one machine in the catalog. Nine of the selected resource groups
remain empty after the catalog is created. You might intend to use them to expand your capacity in the future, so they
remain associated with that catalog. You can't add resource groups to a catalog after the catalog is created, so planning
for future growth is sound practice. However, if another catalog is created, those nine resource groups will appear in the
available list. XenApp and XenDesktop does not currently keep track of which resource groups are allocated to which
catalogs. It's up to you to monitor that.
If your connection uses a service principal that can access empty resource groups in various regions, they will all appear in
the available list. Be sure to choose resource groups in the same region where you're creating the machine catalog.
T roubleshoot ing
Resource groups don't appear in the list on the Resource Groups page of the catalog creation wizard.
T he service principal must have appropriate permissions applied to the resource groups you want to appear in the list.
See the Requirements section above.
When adding machines to a previously-created machine catalog, not all machines are provisioned.
After creating a catalog, and later adding more machines to the catalog, do not exceed the machine capacity of the
resource groups originally selected for the catalog (240 per group). You cannot add resource groups after the catalog
is created. If you attempt to add more machines than the existing resource groups can accommodate, the
provisioning fails.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.88
For example, you create a machine catalog with 300 VMs and 2 resource groups. T he resource groups can
accommodate up to 480 VMs (240 * 2). If you later try to add 200 VMs to the catalog, that exceeds the capacity of
the resource groups (300 current VMs + 200 new VMs = 500, but the resource groups can hold only 480).
More information
Connections and resources
Create machine catalogs
CT X219211: Set up a Microsoft Azure Active Directory account
CT X219243: Grant XenApp and XenDesktop access to your Azure subscription
CT X219271: Deploy hybrid cloud using site-to-site VPN
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.89
Microsoft Azure virtualization environments
Nov 28 , 20 17
Connection configuration
When using Studio to create a Microsoft Azure connection, you need information from the Microsoft Azure Publish
Settings file. T he information in that XML file for each subscription looks similar to the sample below (your actual
management certificate will be much longer):
<Subscription
ServiceManagementUrl="https://management.core.windows.net"
Id="o1455234-0r10-nb93-at53-21zx6b87aabb7p"
Name="Test1"
ManagementCertificate=";alkjdflaksdjfl;akjsdfl;akjsdfl; sdjfklasdfilaskjdfkluqweiopruaiopdfaklsdjfjsdilfasdkl;fjerioup" />
T he following procedure assumes you are creating a connection from Studio, and have launched either the Site creation
wizard or the connection creation wizard.
1. In a browser, go to https://manage.windowsazure.com/publishsettings/index.
2. Download the Publish Settings file.
3. In Studio, on the Connection page of the wizard, after you select the Microsoft Azure connection type, click Import.
4. f you have more than one subscription, you are prompted to select the subscription you want.
T he ID and certificate are automatically and silently imported into Studio.
Power actions using a connection are subject to thresholds. Generally, the default values are appropriate and should not be
changed. However, you can edit a connection and change them (you cannot change these values when you create the
connection). For details, see Edit a connection.
Virtual machines
When creating a Machine Catalog in Studio, selecting the size of each virtual machine depends on the options presented
by Studio, the cost and performance of the selected VM instance type, and scalability.
Studio presents all of the VM instance options that Microsoft Azure makes available in a selected region; Citrix cannot
change this presentation. T herefore, you should be familiar with your applications and their CPU, memory, and I/O
requirements. Several choices are available at difference price and performance points; see the following Microsoft articles
to better understand the options.
MSDN – Virtual Machine and Cloud Service Sizes for Azure: https://msdn.microsoft.com/enus/library/azure/dn197896.aspx
Virtual Machine Pricing: http://azure.microsoft.com/en-us/pricing/details/virtual-machines
Basic tier: VMs prefixed with "Basic" represent the basic disk. T hey are limited primarily by the Microsoft supported IOPS
level of 300. T hese are not recommended for Desktop OS (VDI) or Server OS RDSH (Remote Desktop Session Host)
workloads.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.90
Standard tier: Standard tier VMs appear in four series: A, D, DS, and G.
Series
Appear in Studio as
A
Extra small, small, medium, large, extra large, A5, A6, A7, A8, A9, A10, A11. Medium and large are
recommended to test using Desktop OS (VDI) or Server OS (RDSH) workloads, respectively.
D
Standard_D1, D2, D3, D4, D11, D12, D13, D14. T hese VMs offer SSD for temporary storage.
DS
Standard_DS1, DS2, DS3, DS4, DS11, DS12, DS13, DS14. T hese VMs offer local SSD storage for all disks.
G
Standard_G1 – G5. T hese VMs are for high performance computing.
When provisioning machines in Azure premium storage, be sure to select a machine size that is supported in the premium
storage account.
Cost and perf ormance of VM instance types
For US list pricing, the cost of each VM instance type per hour is available at
http://azure.microsoft.com/en-us/pricing/details/virtual-machines/.
When working with cloud environments, it is important to understand your actual computing requirements. For proof of
concept or other testing activities, it can be tempting to leverage the high-performance VM instance types. It may also be
tempting to use the lowest-performing VMs to save on costs. T he better goal is to use a VM appropriate for the task.
Starting with the best-performing may not get the results you need, and will become very expensive over time - in some
cases, within a week. For lower-performing VM instance types with a lower cost, the performance and usability may not be
appropriate for the task.
For Desktop OS (VDI) or Server OS (RDSH) workloads, testing results using LoginVSI against its medium workload found
that instance types Medium (A2) and Large (A3) offered the best price/performance ratio.
Medium (A2) and Large (A3 or A5) represent the best cost/performance for evaluating workloads. Anything smaller is not
recommended. More capable VM series may offer your applications or users the performance and usability they demand;
however, it is best to baseline against one of these three instance types to determine if the higher cost of a more capable
VM instance type provides true value.
Scalability
Several constraints affect the scalability of catalogs in a hosting unit. Some constraints, such as the number of CPU cores
in an Azure subscription, can be mitigated by contacting Microsoft Azure support to increase the default value (20). Others,
such as the number of VMs in a virtual network per subscription (2048), cannot change.
Currently, Citrix supports 40 VMs in a catalog.
To scale up the number of VMs in a catalog or a host, contact Microsoft Azure support. T he Microsoft Azure default limits
prevent scaling beyond a certain number of VMs; however, this limit changes often, so check the latest information:
http://azure.microsoft.com/en-us/documentation/articles/azure-subscription-service-limits/.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.91
A Microsoft Azure virtual network supports up to 2048 VMs.
Microsoft recommends a limit of 40 standard disk VM images per cloud service. When scaling, consider the number of cloud
services required for the number of VMs in the entire connection. Also consider VMS needed to provide the hosted
applications.
Contact Microsoft Azure support to determine if the default CPU core limitations must be increased to support your
workloads.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.92
Microsoft System Center Virtual Machine Manager
virtualization environments
Nov 28 , 20 17
Follow this guidance if you use Hyper-V with Microsoft System Center Virtual Machine Manager (VMM) to provide virtual
machines.
T his release supports the VMM versions listed in the System requirements article.
You can use Provisioning Services and Machine Creation Services to provision:
Generation 1 Desktop or Server OS VMs
Generation 2 Windows Server 2012 R2, Windows Server 2016, and Windows 10 VMs (with or without Secure Boot)
Upgrade VMM
Upgrade from VMM 2012 to VMM 2012 SP1 or VMM 2012 R2
For VMM and Hyper-V Hosts requirements, see http://technet.microsoft.com/en-us/library/gg610649.aspx. For VMM
Console requirements, see http://technet.microsoft.com/en-us/library/gg610640.aspx.
A mixed Hyper-V cluster is not supported. An example of a mixed cluster is one in which half the cluster is running HyperV 2008 and the other is running Hyper-V 2012.
Upgrade from VMM 2008 R2 to VMM 2012 SP1
If you are upgrading from XenDesktop 5.6 on VMM 2008 R2, follow this sequence to avoid XenDesktop downtime.
1. Upgrade VMM to 2012 (now running XenDesktop 5.6 and VMM 2012)
2. Upgrade XenDesktop to the latest version (now running the latest XenDesktop and VMM 2012)
3. Upgrade VMM from 2012 to 2012 SP1 (now running the latest XenDesktop and VMM 2012 SP1)
Upgrade from VMM 2012 SP1 to VMM 2012 R2
If you are starting from XenDesktop or XenApp 7.x on VMM 2012 SP1, follow this sequence to avoid XenDesktop
downtime.
1. Upgrade XenDesktop or XenApp to the latest version (now running the latest XenDesktop or XenApp, and VMM 2012
SP1)
2. Upgrade VMM 2012 SP1 to 2012 R2 (now running the latest XenDesktop or XenApp, and VMM 2012 R2)
Installation and configuration summary
1. Install and configure a hypervisor.
1. Install Microsoft Hyper-V server and VMM on your servers. All Delivery Controllers must be in the same forest as the
VMM servers.
2. Install the System Center Virtual Machine Manager console on all Controllers.
3. Verify the following account information:
T he account you use to specify hosts in Studio is a VMM administrator or VMM delegated administrator 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.
T he user account used for Studio integration must also be a member of the administrators local security group on
each Hyper-V server to support VM life cycle management (such as VM creation, update, and deletion).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.93
Note: Installing a Controller on a server running Hyper-V is not supported.
2. Create a master VM.
1. Install a Virtual Delivery Agent on the master VM, and select the option to optimize the desktop. T his improves
performance.
2. T ake a snapshot of the master VM to use as a backup.
3. 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 new VMs.
4. In the Host Details dialog box, select the cluster or standalone host to use when creating new VMs.
Important: 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, make sure that credentials meet the
following requirements so that calls from the Controller's Hypervisor 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 as storage, enable the Authentication Credential Security Support Provider (CredSSP) from the
Controller to individual Hyper-V machines when using VMM 2012 SP1 with Hyper-V on Windows Server 2012. For more
information, see CT X137465.
Using a standard PowerShell V3 remote session, the HCL uses CredSSP to open a connection to the Hyper-V machine. T his
feature passes Kerberos-encrypted user credentials to the Hyper-V machine, and the PowerShell commands in the session
on the remote Hyper-V machine run with the credentials provided (in this case, those of the VMM user), so that
communication commands to storage work correctly.
T he 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 new MCS provisioning scheme (machine catalog). It clones and
flattens the master VM ready for creating new VMs from the new disk created (and removes dependency on the original
master VM).
ConvertVirtualHardDisk on the root\virtualization\v2 namespace
Example:
$ims = Get-WmiObject -class $class -namespace "root\virtualization\v2";
$result = $ims.ConvertVirtualHardDisk($diskName, $vhdastext)
$result
Create dif f erence disk - Creates a difference disk from the master image generated by consolidating the master image.
T he difference disk is then attached to a new VM.
CreateVirtualHardDisk on the root\virtualization\v2 namespace
Example:
$ims = Get-WmiObject -class $class -namespace "root\virtualization\v2";
$result = $ims.CreateVirtualHardDisk($vhdastext);
$result
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.94
Upload identity disks - T he HCL cannot directly upload the identity disk to SMB storage. T herefore, 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.
1. T he HCL uploads the Identity to the Hyper-V machine through the administrator share.
2. T he 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).
3. T he HCL deletes the file from the administrator share.
4. When the HCL completes the identity disk upload to the Hyper-V machine, the remote PowerShell session copies the
identity disks to SMB storage and then deletes it from the Hyper-V machine.
T he 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. T he
following process creates a folder that only has VMM user permissions on the Hyper-V server if it does not exist.
1. T he HyperV machine copies the disk from the SMB storage to local Hyper-V storage through a PowerShell script
running in the PowerShell V3 remote session.
2. HCL reads the disk from the Hyper-V machine's administrator share into memory.
3. HCL deletes the file from the administrator share.
Personal vDisk creation - If the administrator creates the VM in a Personal vDisk machine catalog, you must create an
empty disk (PvD).
T he call to create an empty disk does not require direct access to the storage. If you have PvD disks that reside on
different storage than the main or operating system disk, then the use remote PowerShell to create the PvD in a
directory folder that has the same name of the VM from which it was created. For CSV or LocalStorage, do not use
remote PowerShell. Creating the directory before creating an empty disk avoids VMM command failure.
From the Hyper-V machine, perform a mkdir on the storage.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.95
VMware virtualization environments
Nov 28 , 20 17
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 (described in
https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2101567). If you
disable this feature, MCS does not work correctly.
Required privileges
Create a VMware user account and one or more VMware roles with a set or all of the privileges listed below. Base the roles'
creation on the specific level of granularly required over the user’s permissions to request the various XenApp or
XenDesktop operations at any time. To grant the user specific permissions at any point, associate them with the respective
role, at the DataCenter level at a minimum.
T he following tables show the mappings between XenApp and XenDesktop operations and the minimum required VMware
privileges.
Add connection and resources
SDK
User interf ace
System.Anonymous, System.Read, and System.View
Added automatically. Can use the built-in
read-only role.
Provision machines (Machine Creation Services)
SDK
User interf ace
Datastore.AllocateSpace
Datastore > Allocate space
Datastore.Browse
Datastore > Browse datastore
Datastore.FileManagement
Datastore > Low level file operations
Network.Assign
Network > Assign network
Resource.AssignVMToPool
Resource > Assign virtual machine to resource pool
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.96
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
vSphere 5.0, Update 2 and vSphere 5.1, Update 1: Virtual machine > State
VirtualMachine.State.CreateSnapshot
> 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:
SDK
User interf ace
Global.ManageCustomFields
Global > Manage custom attributes
Global.SetCustomField
Global > Set custom attribute
To ensure that you use a clean base image for creating new VMs, tag VMs created with Machine Creation Services to
exclude them from the list of VMs available to use as base images.
Provision machines (Provisioning Services)
All privileges from "Provision machines (Machine Creation Services)" and:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.97
SDK
User interf ace
VirtualMachine.Config.AddRemoveDevice
VirtualMachine.Config.CPUCount
Virtual machine > Configuration > Add or remove
device
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 interf ace
VirtualMachine.Interact.PowerOff
Virtual machine > Interaction > Power Off
VirtualMachine.Interact.PowerOn
Virtual machine > Interaction > Power On
VirtualMachine.Interact.Reset
Virtual machine > Interaction > Reset
VirtualMachine.Interact.Suspend
Virtual machine > Interaction > Suspend
Image update and rollback
SDK
User interf ace
Datastore.AllocateSpace
Datastore > Allocate space
Datastore.Browse
Datastore > Browse datastore
Datastore.FileManagement
Datastore > Low level file operations
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.98
Network.Assign
Network > Assign network
Resource > Assign virtual machine to resource
Resource.AssignVMToPool
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.Interact.Reset
Virtual machine > Interaction > Reset
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
Delete provisioned machines
SDK
User interf ace
Datastore.Browse
Datastore > Browse datastore
Datastore.FileManagement
Datastore > Low level file operations
VirtualMachine.Config.RemoveDisk
Virtual machine > Configuration > Remove disk
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.99
VirtualMachine.Interact.PowerOff
Virtual machine > Interaction > Power Off
VirtualMachine.Inventory.Delete
Virtual machine > Inventory > Remove
Create AppDisks (valid for VMware vSphere minimum version 5.5 and XenApp and XenDesktop minimum version 7.8)
SDK
User interf ace
Datastore.AllocateSpace
Datastore > Allocate space
Datastore.Browse
Datastore > Browse datastore
Datastore.FileManagement
Datastore > Low level file operations
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.EditDevice
Virtual machine > Configuration > Modify Device
Settings
VirtualMachine.Config.RemoveDisk
Virtual machine > Configuration > Remove disk
VirtualMachine.Interact.PowerOff
Virtual machine > Interaction > Power Off
VirtualMachine.Interact.PowerOn
Virtual machine > Interaction > Power On
Delete AppDisks (valid for VMware vSphere minimum version 5.5 and XenApp and XenDesktop minimum version 7.8 )
SDK
User interf ace
Datastore.Browse
Datastore > Browse datastore
Datastore.FileManagement
Datastore > Low level file operations
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.100
VirtualMachine.Config.RemoveDisk
Virtual machine > Configuration > Remove disk
VirtualMachine.Interact.PowerOff
Virtual machine > Interaction > Power Off
Obtain and import a certificate
To protect vSphere communications, Citrix recommends that you use HT T PS rather than HT T P. HT T PS requires digital
certificates. Citrix recommends you use 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, and your organization's security policy
permits it, you can use the VMware-installed self-signed certificate. Add the VMware vCenter certificate to each Controller.
Follow this procedure:
1. Add the fully qualified domain name (FQDN) of the computer running vCenter Server to the hosts file on that server,
located at %SystemRoot%/WINDOWS/system32/Drivers/etc/. T his 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 methods:
From the vCenter server:
1. Copy the file rui.crt from the vCenter server to a location accessible on your Delivery Controllers.
2. 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, depending on your user account,
you may need to right-click on Internet Explorer and choose Run as Administrator to download or install the
certificate.
1. Open your web browser and make a secure web connection to the vCenter server; for example
https://server1.domain1.com
2. Accept the security warnings.
3. Click on the address bar where it shows the certificate error.
4. View the certificate and click on the Details tab.
5. Select Copy to file and export in .CER format, providing a name when prompted to do so.
6. Save the exported certificate.
7. Navigate to the location of the exported certificate and open the .CER file.
Import directly from Internet Explorer running as an administrator:
1. Open your web browser and make a secure web connection to the vCenter server; for example
https://server1.domain1.com.
2. Accept the security warnings.
3. Click on the address bar where it shows the certificate error.
4. View the certificate.
Import the certificate into the certificate store on each of your Controllers:
1. Click Install certificate, select Local Machine, and then click Next.
2. Select Place all certificates in the following store, and then click Browse.
3. If you are using Windows Server 2008 R2:
1. Select the Show physical stores check box.
2. Expand T rusted People.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.101
3. Select Local Computer.
4. Click Next, then click Finish.
If you are using Windows Server 2012, Windows Server 2012 R2, or Windows Server 2016:
1. Select T rusted People, then click OK.
2. Click Next, then click Finish.
Important: 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.
Create a master VM
Use a master VM to provide user desktops and applications. On your hypervisor:
1. Install a VDA on the master VM, selecting the option to optimize the desktop, which improves performance.
2. T ake a snapshot of the master VM to use as a back-up.
Create virtual desktops
If you are using Studio to create VMs, rather than selecting an existing Machine Catalog, specify the following information
when setting up your hosting infrastructure to create virtual desktops.
1. Select the VMware vSphere host type.
2. Enter the address of the access point for the vCenter SDK.
3. Enter the credentials for the VMware user account you set up earlier that has permissions to create new VMs. Specify
the username in the form domain/username.
VMware SSL thumbprint
T he VMware SSL thumbprint feature addresses a frequently-reported error when creating a host connection to a VMware
vSphere hypervisor. Previously, administrators had to manually create a trust relationship between the Delivery Controllers in
the Site and the hypervisor's certificate before creating a connection. T he VMware SSL thumbprint feature removes that
manual requirement: the untrusted certificate's thumbprint is stored on the Site database so that the hypervisor can be
continuously identified as trusted by XenApp or XenDesktop, 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.102
Microsoft System Center Configuration Manager
environments
Nov 28 , 20 17
Sites that use Microsoft System Center Configuration Manager (Configuration Manager) to manage access to applications
and desktops on physical devices can extend that use to XenApp or XenDesktop through these integration options.
Citrix Connector 7.5 f or Conf iguration Manager 2012 – Citrix Connector provides a bridge between Configuration
Manager and XenApp or XenDesktop. T he Connector enables you to unify day-to-day operations across the physical
environments you manage with Configuration Manager and the virtual environments you manage with XenApp or
XenDesktop. For information about the Connector, see Citrix Connector 7.5 for System Center Configuration Manager
2012 .
Conf iguration Manager Wake Proxy f eature – T he Remote PC Access Wake on LAN feature requires Configuration
Manager. For more information, see below.
XenApp and XenDesktop properties – XenApp and XenDesktop properties enable you to identify Citrix virtual
desktops for management through Configuration Manager. T hese properties are automatically used by the Citrix
Connector but can also be manually configured, as described in the following section.
Properties
Properties are available to Microsoft System Center Configuration Manager to manage virtual desktops.
Boolean properties displayed in Configuration Manager may appear as 1 or 0, not true or false.
T he 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
User – Sets IsAssigned to T rue
BrokerSiteName
Site; returns the same value as HostIdentifier.
DesktopCatalogName
Machine catalog associated with the desktop.
DesktopGroupName
Delivery Group associated with the desktop.
HostIdentifier
Site; returns the same value as BrokerSiteName.
IsAssigned
True to assign the desktop to a user, set to False for a random desktop.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.103
IsMasterImage
Property
Allows
decisions about the environment. For example, you may want to install
Description
applications on the master image and not on the provisioned machines, especially if
those machines are in a clean state on boot machines. Valid values are:
T rue on a VM that is used as a master image (this value is set during installation based
on a selection).
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
T he location where Configuration Manager stores persistent data. T his is not accessible
to users.
PersonalvDiskDriveLetter
For a desktop with a Personal vDisk, the drive letter you assign to the Personal vDisk.
BrokerSiteName,
Determined when the desktop registers with the Controller; they are null for a desktop
DesktopCatalogName,
that has not fully registered.
DesktopGroupName,
HostIdentifier
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 may include spaces or vary slightly from the property names. For
example, BrokerSiteName may appear 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.
Configuration Manager and Remote PC Access Wake on LAN
To configure the Remote PC Access Wake on LAN feature, complete the following before installing a VDA on the office
PCs and using Studio to create or update the Remote PC Access deployment:
Configure ConfigMgr 2012, 2012 R2, or 2016 within the organization. T hen deploy the ConfigMgr client to all Remote PC
Access machines, allowing time for the scheduled SCCM inventory cycle to run (or force one manually, if required). T he
access credentials you specify in Studio to configure the connection to ConfigMgr must include collections in the scope
and the Remote T ools Operator role.
For Intel Active Management T echnology (AMT ) support:
T he minimum supported version on the PC must be AMT 3.2.1.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.104
Provision the PC for AMT use with certificates and associated provisioning processes.
Only ConfigMgr 2012 and 2012 R2 can be used, not ConfigMgr 2016.
For ConfigMgr Wake Proxy and/or magic packet support:
Configure Wake on LAN in each PC's BIOS settings.
For Wake Proxy support, enable the option in ConfigMgr. For each subnet in the organization that contains PCs that
will 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 Remote PC Access
deployment in Studio.
If you enable power management, specify connection details: the ConfigMgr address and access credentials, plus a
name.
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 and specify the new power
management connection.
You can edit a power management connection to configure the use of the ConfigMgr Wake Proxy and magic packets, as
well as change the packet transmission method.
For more information, see Remote PC Access.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.105
Nutanix virtualization environments
Nov 28 , 20 17
Follow this guidance when using Nutanix Acropolis to provide virtual machines in your XenApp or XenDesktop deployment.
T he setup process includes the following tasks:
Install and register the Nutanix plugin in your XenApp or XenDesktop 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 Acropolix MCS Plugin Installation Guide, available at the Nutanix Support Portal:
https://portal.nutanix.com.
Install and register the Nutanix plugin
After you install the XenApp or XenDesktop components, complete the following procedure to install and register the
Nutanix plugin on the Delivery Controllers. You will then be able to use Studio to create a connection 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 plugin 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 plugin has been registered:
Add-PSSnapin Citrix*
Get-HypHypervisorPlugin
Create a connection to Nutanix
See the Create a Site and Connections and resources articles for complete information about all pages in the wizards that
create a connection.
In the Site Setup or Add Connection and Resources wizard, select the Nutanix connection type on the Connection page,
and then 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
T his information is a supplement to the guidance in the Create Machine Catalogs article. It describes only the fields that are
unique to Nutanix.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.106
T he snapshot you select is the template that will be used to create the VMs in the Machine Catalog. Before creating the
Machine 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 referenced above.
T he Operating System and Machine Management pages do not contain Nutanix-specific information. 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 will be placed.
On the Master Image page, select the image snapshot. Acropolis snapshot names must be prefixed with "XD_" to be used
in XenApp and XenDesktop. 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.
T he Network Cards, Computer Accounts, and Summary pages do not contain Nutanix-specific information. Follow the
guidance in the Create Machine Catalogs article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.107
Install core components
Nov 28 , 20 17
T he core components are the Delivery Controller, Studio, Director, StoreFront, and License Server.
Important: Before you start an installation, review Prepare to install. Also, review this article before starting an installation.
T his 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 XenApp and XenDesktop 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 account.
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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.108
Click Start next to the product to install: XenApp or XenDesktop.
(If the machine already has XenApp or XenDesktop components installed on it, this page does not appear.)
Command-line option: /xenapp to install XenApp; XenDesktop is installed 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 components to install on
this machine.)
If you've already installed a Controller (on this machine or another) and want to install another component, select the
component from the Extend Deployment section.
Command-line option: /components
Step 4. Read and accept the license agreement
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.109
On the Licensing Agreement page, after you read the license agreement, indicate that you have read and accepted it.
T hen click Next.
Step 5. Select the components to install and the
installation location
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.110
On the Core components page:
Location: By default, components are installed in C:\Program Files\Citrix. T he 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 core components on one
server is fine for proof of concept, test, or small production deployments. 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. T hat alert reminds you
to install that component, although not necessarily on this machine.
Click Next.
Command-line options: /installdir, /components, /exclude
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 default, this selection is
enabled. If you're not familiar with the XenApp and XenDesktop 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 shadowing. Enabling shadowing opens T CP port
3389. By default, this feature is enabled. T he default setting is fine for most deployments. T his feature appears only
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.111
when you are installing Director.
Click Next.
Command-line options: /nosql (to prevent installation), /no_remote_assistance (to prevent enabling)
Step 7. Open Windows firewall ports automatically
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. T he default setting is fine for most deployments. For port information, see Network ports.
Click Next.
(T he graphic shows the port lists when you install all the core components on this machine. T hat type of installation is
usually done only for test deployments.)
Command-line option: /configure_firewall
Step 8. Review prerequisites and confirm installation
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.112
T he 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.
T he display shows the progress of the installation:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.113
Step 9. Connect to Smart Tools and Call Home
When installing or upgrading a Delivery Controller, the Smart Agent page offers several options:
Enable connections to Smart T ools and Call Home. T his is the recommended selection.
Enable connections to Call Home. During an upgrade, this option does not appear if Call Home is already enabled or if
the installer encounters an error related to the Citrix T elemetry Service.
Do not enable connections to Smart T ools or Call Home.
If you install StoreFront (but not a Controller), the wizard displays the Call Home page, which allows you to participate in
Call Home. If you install other core components (but not a Controller or StoreFront), the wizard does not display either the
Smart Tools or Call Home pages.
If you choose an option to enable connections to Smart Tools and/or Call Home:
1. Click Connect.
2. Provide your Citrix or Citrix Cloud credentials.
3. After your credentials are validated, the process downloads a Smart Agent certificate. After this completes successfully,
a green check mark appears next to the Connect button. If an error occurs during this process, change your
participation selection (to "I do not want to …"). You can enroll later.
4. Click Next to continue with the installation wizard.
If you choose not to participate, click Next.
Command-line option: /exclude "Smart Tools Agent" (to prevent installation)
Step 10. Finish this installation
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.114
T he 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 core components. You can also install more Controllers on other servers.
Next steps
After you install all the required core 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 components:
Universal Print Server server component: Launch the installer on the print server. Select Universal Print Server in the
Extend Deployment section. Accept the license agreement, then proceed to the end of the wizard. T here is nothing else
to specify or select. T o install this component form the command line, see Install using the command line.
Federated Authentication Service: See Federated Authentication Service.
Self-Service Password Reset Service: See the current Self-Service Password Reset Service documentation.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.115
Install VDAs
Nov 28 , 20 17
T here are two types of VDAs for Windows machines: VDA for Server OS and VDA for Desktop OS. (For information about
VDAs for Linux machines, see the Linux Virtual Delivery Agent documentation.)
Important: Before you start an installation, review Prepare to install. For example, the machine should have the latest
Windows updates. If required updates are not present (such as KB2919355), installation fails.
Before installing VDAs, you should have already installed the core components. You can also create the Site before
installing VDAs.
T his article describes the installation wizard sequence when installing a VDA. Command-line equivalents 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:
If you haven't downloaded the XenApp and XenDesktop ISO yet:
Use your Citrix account credentials to access the XenApp and XenDesktop download page. Download the product
ISO file.
Unzip the file. Optionally, burn a DVD of the ISO file.
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.
T he installation wizard launches.
If you're using a standalone package:
Use your Citrix account credentials to access the XenApp and XenDesktop download page. Download the appropriate
package:
Component name on download page
Installer file name
Server OS Virtual Delivery Agent <version>
VDAServerSetup.exe
Desktop OS Virtual Delivery Agent <version>
VDAWorkstationSetup.exe
Desktop OS Core Services Virtual Delivery Agent <version>
VDAWorkstationCoreSetup.exe
Right-click the package and choose Run as administrator.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.116
T he installation wizard launches.
Step 2. Choose which product to install
Click Start next to the product to install: XenApp or XenDesktop. (If the machine already has a XenApp or XenDesktop
component installed, this page does not appear.)
Command-line option: /xenapp to install XenApp; XenDesktop is installed if option is omitted
Step 3. Select the VDA
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.117
Select the Virtual Delivery Agent entry. T he installer knows whether it's running on a Desktop or Server OS, so it offers only
the appropriate VDA type.
For example, when you run the installer on a Windows 10 machine, the VDA for Desktop OS option is available. T he VDA for
Server OS option is not offered.
If you attempt to install (or upgrade to) a Windows VDA on an OS that is not supported for this XenApp and XenDesktop
version, a message guides you to a CT X article that describes your options.
Step 4. Specify how the VDA will be used
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.118
On the Environment page, specify how you plan to use the VDA. Choose one of the following:
Master image: (default) You are installing the VDA on a machine image. You plan to use Citrix tools (Machine Creation
Services or Provisioning Services) to create VMs from that master image.
Enable connections to a server machine (if installing on a server) or Remote PC Access (if installing on a desktop
machine): You are installing the VDA on a physical machine or on a VM that was provisioned without a VDA. If you
choose the Remote PC Access option, the following components are not installed/enabled:
App-V
User Profile Manager
Machine Identify Service
Personal vDisk
Click Next.
Command-line options: /masterimage, /remotepc
If you are using the VDAWorkstationCoreSetup.exe installer, this page does not appear in the wizard and the command-line
options are not valid.
Step 5. Select the components to install and the
installation location
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.119
On the Core components page:
Location: By default, components are installed in C:\Program Files\Citrix. T his 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 Receiver for Windows is installed with the VDA (unless you are using the
VDAWorkstationCoreSetup.exe installer). Clear the check box if you do not want that Citrix Receiver installed. If you are
using the VDAWorkstationCoreSetup.exe installer, Citrix Receiver for Windows is never installed, so this check box is not
displayed.
Click Next.
Command-line options: /installdir, "/components vda" to prevent Citrix Receiver for Windows installation
Step 6. Install additional components
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.120
T he Additional Components page contains check boxes to enable or disable installation of other features and
technologies with the VDA. T his 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.)
Citrix Personalization f or App-V:
Install this component if you use applications from Microsoft App-V packages. For details, see App-V.
Command-line option: /exclude "Citrix Personalization for App-V – VDA" to prevent component installation
Citrix AppDisk / Personal vDisk:
Valid only when installing a VDA for Desktop OS on a VM. Installs components used for AppDisk and Personal vDisk.
For more information, see AppDisks and Personal vDisk.
Command-line option: /exclude "Personal vDisk" to prevent AppDisk and Personal vDisk component installation
Citrix PDF Printer Driver
Installs the Citrix PDF Universal Print Driver.
Command-line option: /exclude "Citrix PDF Printer Driver" to prevent component installation
Citrix User Profile Manager:
T his component manages user personalization settings in user profiles. For details, see Profile Management.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.121
Excluding Citrix Profile management from the installation affects the 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 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 management Service is not required.
Command-line option: /exclude "Citrix User Profile Manager" to prevent component installation
Citrix User Profile Manager WMI Plugin:
T his 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: /exclude "Citrix User Profile Manager WMI Plugin" to prevent component installation
Citrix Machine Identity Service:
T his service prepares the master image for a MCS-provisioned catalog. T he service also manages each provisioned
machine's unique Active Directory identity.
Command-line option: /exclude "Machine Identity Service" to prevent component installation
Default values in the graphical interface:
If you select "Create a master image" on the Environment page (Step 4), items on the Additional Components page
are enabled by default.
If you select "Enable Remote PC Access" or "Enable connections to a server machine" on the Environment page, items
on the Additional Components page are disabled by default.
Step 7. Delivery Controller addresses
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.122
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"). T he 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 additional
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. T o specify addresses later, you can either rerun the installer or use Citrix Group Policy. T he wizard also
reminds you on the Summary page.
Choose locations f rom 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:
T he address cannot contain the 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 Controller are open. T hat
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
Delivery Controllers.
Command-line option: /controllers
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.123
Step 8. Enable or disable features
On the Features page, use the check boxes to enable or disable features you want to use.
Optimize perf ormance:
Valid only when installing a VDA on a VM, not a physical machine. When this feature is enabled (default), the
optimization tool is used for VDAs running in a VM on a hypervisor. VM optimization includes disabling offline files,
disabling background defragmentation, and reducing event log size. For details, see CT X125874.
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 f or audio:
Enable this feature if voice-over-IP is widely used in your network. T he feature reduces latency and improves audio
resilience over lossy networks. It allows audio data to be transmitted using RT P over UDP transport. (Default =
disabled)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.124
Command-line option: /enable_real_time_transport
Framehawk:
When this feature is enabled, bidirectional UDP ports 3224-3324 are opened. (Default = disabled)
You can change the port range later with the "Framehawk display channel port range" Citrix policy setting. You must
then open local firewall ports. A UDP network path must be open on any internal (VDA to Citrix Receiver or NetScaler
Gateway) and external (NetScaler Gateway to Citrix Receiver) firewalls. If NetScaler Gateway is deployed, Framehawk
datagrams are encrypted using DT LS (default UDP port 443). For details, see the Framehawk article.
Command-line option: /enable_framehawk_port
AppDisk / Personal vDisk:
Valid only when installing a VDA for Desktop OS on a VM. T his check box is available only if the Citrix AppDisk /
Personal vDisk check box is selected on the Additional Components page. When this check box is enabled, AppDisks
and Personal vDisks can be used. For details, see AppDisks and Personal vDisks.
Command-line option: /baseimage
If you are using the VDAWorkstationCoreSetup.exe installer, this feature does not appear in the wizard and the
command-line option is not valid.
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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.125
firewall is not enabled. T his 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
T he 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 may restart once or twice. See Prepare to install.
Step 11. Participate in Call Home
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.126
On the Smart Tools page, choose whether to participate in Citrix Call Home, which is now a part of Citrix Smart Tools. If
you choose to participate (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.
Step 12. Complete this installation
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.127
T he 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: Install other VDAs and continue configuration
Repeat the steps 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 machine catalogs
Create Delivery Groups
Later, if you want 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. T hen right-click and select Change.
2. Select Customize Virtual Delivery Agent Settings. When the installer launches, you can change:
Controller addresses
T CP/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 installation 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. T he machine's Windows Programs and Features display shows the actual VDA version.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.128
Install using the command line
Jan 24 , 20 18
T his article applies to installing components on machines with Windows operating systems. For information about VDAs for
Linux operating systems, see the Linux Virtual Delivery Agent documentation.
In this article:
Use the full-product installer
Use a standalone VDA installer
Command-line options for installing core components
Examples: Install core components
Command-line options for installing a VDA
Examples: Install a VDA
Customize a VDA using the command line
Install the Universal Print Server using the command line
Important: T his article describes how to issue product installation commands. Before beginning any installation, review the
Prepare to install article. T hat 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 machines in Active Directory. For details, see Install VDAs using scripts.
If you attempt to install (or upgrade to) a Windows VDA on an OS that is not supported for this XenApp and XenDesktop
version, a message guides you to a CT X article that describes your options.
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 account.
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 the XenDesktopServerSetup.exe command, with the options listed in Command-line options for installing core
components.
To install a VDA:
Run the XenDesktopVDASetup.exe command with the options listed in Command-line options for installing a VDA.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.129
To install the Universal Print Server:
Follow the guidance in Install the Universal Print Server using the command line.
To install the Federated Authentication Service:
Citrix recommends using the graphical interface.
To install the Self-Service Password Reset Service:
Follow the guidance in the Self-Service Password Reset Service documentation.
Use a standalone VDA installer
Citrix account credentials are required to access the download site. You must either have elevated administrative privileges
before starting the installation or use Run as administrator.
Download the appropriate package from Citrix:
Component name on download page
Installer file name
Server OS Virtual Delivery Agent <version>
VDAServerSetup.exe
Desktop OS Virtual Delivery Agent <version>
VDAWorkstationSetup.exe
Desktop OS Core Services Virtual Delivery Agent <version>
VDAWorkstationCoreSetup.exe
Either extract the files from the package to an existing directory first and then run the installation command, or just run
the package.
To extract the files before installing them, use /extract with the absolute path, for example
.\VDAWorkstationCoreSetup.exe /extract %temp%\CitrixVDAInstallMedia. (T he directory must exist. Otherwise, the
extract fails.) T hen in a separate command, run XenDesktopVdaSetup.exe from the directory containing the
extracted content (in the example above, CitrixVDAInstallMedia). Use the valid options in Command-line options for
installing a VDA.
To run the downloaded package, just run its name: VDAServerSetup.exe, VDAWorkstationSetup.exe, or
VDAWorkstationCoreSetup.exe. Use the valid options in Command-line options for installing a VDA.
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.
T he VDAWorkstationCoreSetup.exe installer is different, because it supports a subset of the options available
to the other installers.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.130
Command-line options for installing core components
T he 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:
CONT ROLLER: Controller
DESKTOPST UDIO: Studio
DESKTOPDIRECTOR: Director
LICENSESERVER: Citrix License Server
STOREFRONT : StoreFront
If this option is omitted, all components are installed (or removed, if the /remove option is also specified).
/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
Prevents installation of one or more comma-separated features, services, or technologies, each enclosed in quotation
marks. Valid values are:
"Local Host Cache Storage (LocalDB)": Prevents installation of the database used for Local Host Cache. T his option
has no effect on whether or not SQL Server Express is installed for use as the Site database.
"Smart Tools Agent": Prevents installation of the Citrix Smart Tools agent.
/help or /h
Displays command help.
/installdir <directory>
Existing empty directory where components will be installed. Default = c:\Program Files\Citrix.
/logpath <path>
Log file location. T he specified folder must exist. T he installer does not create it. Default =
"%T EMP%\Citrix\XenDesktop Installer"
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.131
/no_remote_assistance
Valid only when installing Director. Disables the user shadowing feature that uses Windows Remote Assistance.
/noreboot
Prevents a restart after installation. (For most core components, a restart is not enabled by default.)
/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. (T his 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. T he only evidence of the installation process is in Windows Task
Manager. If this option is omitted, the graphical interface launches.
/remove
Removes the core components specified with the /components option.
/removeall
Removes all installed core components.
/sendexperiencemetrics
Automatically sends analytics collected during the installation, upgrade, or removal to Citrix. If this option is omitted
(or /disableexperiencemetrics is specified), the analytics are collected locally, but not sent automatically.
/tempdir <directory>
Directory that holds temporary files during installation. Default = c:\Windows\Temp.
/xenapp
Installs XenApp. If this option is omitted, XenDesktop is installed.
Examples: Install core components
T he following command installs a XenDesktop 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
T he following command installs a XenApp 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.132
/configure_firewall
Command-line options for installing a VDA
T he following options are valid with one or more of the following commands: XenDesktopVDASetup.exe,
VDAServerSetup.exe, VDAWorkstationSetup.exe, or VDAWorkstationCoreSetup.exe.
/baseimage
Valid only when installing a VDA for Desktop OS on a VM. Enables the use of Personal vDisks with a master image. For
details, see Personal vDisk.
T his option is not valid when using the VDAWorkstationCoreSetup.exe installer.
/components <component >[,<component >]
Comma-separated list of components to install or remove. Valid values are:
VDA: Virtual Delivery Agent
PLUGINS: Citrix Receiver for Windows (CitrixReceiver.exe)
For example, to install the VDA but not Citrix Receiver, specify /components vda.
If this option is omitted, all components are installed.
T his option is not valid when using the VDAWorkstationCoreSetup.exe installer. T hat installer cannot install a Citrix
Receiver.
/controllers "<controller> [<controller>] [...]"
Space-separated FQDNs of Controllers with which the VDA can communicate, enclosed in 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_framehawk_port
Opens the UDP ports used by Framehawk. Default = false
/enable_hdx_ports
Opens ports in the Windows firewall required by the Controller and enabled features (except Windows Remote
Assistance), if the Windows Firewall Service is detected, even if the firewall is not enabled. If you are using a different
firewall or no firewall, you must configure the firewall manually. For port information, see Network ports.
T ip: To open the UDP ports that HDX adaptive transport uses to communicate with the Controller, specify the
/enable_hdx_udp_ports option, in addition to the /enable_hdx_ports option.
/enable_hdx_udp_ports
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.133
Opens UDP ports in the Windows firewall that are required by HDX adaptive transport, if the Windows Firewall Service
is detected, even if the firewall is not enabled. If you are using a different firewall or no firewall, you must configure
the firewall manually. For port information, see Network ports.
T ip: To open additional ports that the VDA uses to communicate with the Controller and enabled features, specify
the /enable_hdx_ports option, in addition to the /enable_hdx_udp_ports option.
/enable_real_time_transport
Enables or disables use of UDP for audio packets (Real-T ime Audio Transport for audio). Enabling this feature can
improve audio performance. Include the /enable_hdx_ports option if you want the UDP ports opened automatically
when the Windows Firewall Service is detected.
/enable_remote_assistance
Enables the shadowing feature in Windows Remote Assistance for use with Director. If you specify this option,
Windows Remote Assistance opens the dynamic ports in the firewall.
/exclude "<component >"[,"<component >"]
Prevents installation of one or more comma-separated optional components, each enclosed in quotation marks. For
example, installing or upgrading a VDA on an image that is not managed by MCS does not require the Personal vDisk
or Machine Identity Service components. Valid values are:
Personal vDisk
Machine Identity Service
Citrix User Profile Manager
Citrix User Profile Manager WMI Plugin
Citrix Universal Print Client
Citrix Telemetry Service
Citrix Personalization for App-V - VDA
Citrix PDF Printer Driver
Excluding Citrix Profile management from the installation (using the /exclude "Citrix User Profile Manager" option)
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 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 management Service is not required.
T his option is not valid when using the VDAWorkstationCoreSetup.exe installer. T hat installer automatically excludes
many of these items.
/h or /help
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.134
Displays command help.
/hdxflashv2only
Prevents installation of Flash redirection legacy binaries, for enhanced security.
T his option is not available in the graphical interface.
/installdir <directory>
Existing empty directory where components will be installed. Default = c:\Program Files\Citrix.
/logpath <path>
Log file location. T he specified folder must exist. T he installer does not create it. Default =
"%T EMP%\Citrix\XenDesktop Installer"
T his 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.
T his option is not valid when using the VDAWorkstationCoreSetup.exe installer.
/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, with the exception of N editions.
/nodesktopexperience
Valid only when installing a VDA for Server OS. Prevents enabling of the Enhanced Desktop Experience feature. T his
feature is also controlled with the Enhanced Desktop Experience Citrix policy setting.
/noreboot
Prevents a restart after installation. T he VDA cannot be used until after a restart.
/noresume
By default, when a machine restart is needed during an installation, the installer resumes automatically after the
restart completes. To override the default, specify /noresume. T his can be helpful if you must re-mount the media or
want to capture information during an automated installation.
/optimize
Valid only when installing a VDA on a VM. Enables optimization for VDAs running in a VM on a hypervisor. VM
optimization includes disabling offline files, disabling background defragmentation, and reducing event log size. Do not
specify this option for Remote PC Access deployments. For more information, see CT X125874.
/portnumber <port >
Valid only when the /reconfig option is specified. Port number to enable for communications between the VDA and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.135
the Controller. T he previously configured port is disabled, unless it is port 80.
/quiet or /passive
No user interface appears during the installation. T he only evidence of the installation and configuration process is in
Windows Task Manager. If this option is omitted, the graphical interface launches.
/reconfig
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. Excludes installation of the following components on a Desktop OS:
Citrix Personalization for App-V
Citrix User Profile Manager
Citrix User Profile Manager WMI Plugin
Machine Identity Service
Personal vDisk
Citrix PDF Printer Driver
T his option is not valid when using the VDAWorkstationCoreSetup.exe installer. T hat installer 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), the analytics are collected locally, but not sent automatically.
/servervdi
Installs a VDA for Desktop OS on a supported Windows server. Omit this option when installing a VDA for Server OS
on a Windows server. Before using this option, see Server VDI.
T his option should be used only with the full-product VDA installer. T his option is not available in the graphical
interface.
/site_guid <guid>
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.136
Globally Unique Identifier of the site Active Directory Organizational Unit (OU). T his associates a virtual desktop with a
Site when you are using Active Directory for discovery (auto-update is the recommended and default discovery
method). T he 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.
T his option is not available in the graphical interface.
/virtualmachine
Valid only when installing a VDA on a VM. Overrides detection by the installer of a physical machine, where BIOS
information passed to VMs makes them appear as physical machines.
T his option is not available in the graphical interface.
Examples: Install a VDA
Install a VDA with the f ull-product installer:
T he following command installs a VDA for Desktop OS and Citrix Receiver to the default location on a VM. T his VDA will be
used as a master image. T he VDA will register initially with the Controller on the server named 'Contr-Main' in the domain
'mydomain.' T he VDA will use Personal vDisks, the optimization feature, and Windows Remote Assistance.
\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /quiet /components vda,plugins /controllers "ContrMain.mydomain.local" /enable_hdx_ports /optimize /masterimage /baseimage /enable_remote_assistance
Install a Desktop OS VDA with the VDAWorkstationCoreSetup standalone installer:
T he following command installs a Core Services VDA on a Desktop OS for use in a Remote PC Access or VDI deployment.
Citrix Receiver and other non-core services are not installed. T he address of a Controller is specified, and ports in the
Windows Firewall Service will be opened automatically. T he administrator will handle restarts.
VDAWorkstationCoreSetup .exe /quiet /controllers "Contr-East.domain.com" /enable_hdx_ports /noreboot
Customize a VDA using the command line
After you install a VDA, you can customize several settings. From the \x64\XenDesktop Setup directory on the product
media, run the XenDesktopVdaSetup.exe command, 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.137
/enable_hdx_ports
Install the Universal Print Server using the command
line
Run one of the following commands on each print server:
On a supported 32-bit operating system: From the \x86\Universal Print Server\ directory on the Citrix installation media,
run UpsServer_x86.msi.
On a supported 64-bit operating system: From the \x64\Universal Print Server\ directory on the Citrix installation media,
run UpsServer_x64 .msi.
After you install the Universal Print Server component on your print servers, configure it using the guidance in Provision
printers.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.138
Install VDAs using scripts
Nov 28 , 20 17
T his 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.
T he 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 Provisioning
Services.
Required access:
T he scripts need Everyone Read access to the network share where the VDA installation command is located. T he
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. T o 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. T he 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. T hose tools offer an alternative to searching locally on the target machines.
Important: 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. T he
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 required.
Specify the network share where the installer will be invoked. Point to the root of the layout (the highest point of the
tree). T he 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. T he /quiet and /noreboot options
are included by default in the script and are required: SET COMMANDLINEOPT IONS=/QUIET /NOREBOOT .
3. Using Group Policy Startup Scripts, assign the script to the OU containing your machines. T his 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.139
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.
T he 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 required.
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. T his 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. T he VDA is removed from each machine.
Troubleshoot
T he script generates internal log files that describe script execution progress. T he 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. T he script places two debugging log files in the %temp% folder on each machine:
Kickoff_VDA_Startup_Script_<DateT imeStamp>.log
VDA_Install_ProcessLog_<DateT imeStamp>.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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.140
Create a Site
Nov 28 , 20 17
A Site is the name you give to a XenApp or XenDesktop 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.
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. T he 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.
T he user who creates a Site becomes a full administrator; for more information, see Delegated Administration.
Review this article before you start the Site creation wizard.
To create a Site:
Open Studio if it is not already open. You are automatically guided to the action that starts the Site creation wizard. T he
wizard pages cover the following configuration:
Site type and name
T here are two Site types; choose one:
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).
Databases
T he 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. T hat 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 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 Controllers to the Site, and have already installed the Controller software on other servers, you
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.141
can add those Controllers from this page. If you plan to generate scripts that set up the databases, add the Controllers
before generating the scripts.
Licensing
Consider whether you will use existing licenses or the 30-day free trial that allows you to add license files later. You can also
add or download license files from within the Site creation wizard. For details, see the Licensing documentation.
Specify the License Server address in the form name:[port ]. T he 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 in
the wizard until a successful connection is made to the License Server.
Power management (Remote PC Access only)
See Remote PC Access.
Host connection, network, and storage
If you are using VMs on a hypervisor or cloud 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.
Connection page: See Connection type information sources.
If you are not using VMs on a hypervisor or cloud 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 Microsof t
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.
Storage and Network pages: See Host storage, Storage management, and Storage selection for details about storage
types and management methods.
Additional Features
You can select features to customize your Site. When you select the check box for an item that requires information, a
configuration box appears.
AppDNA Integration
Valid if you use AppDisks and have installed AppDNA. AppDNA integration allows analysis of applications in the
AppDisks. You can then review compatibility issues and take remedial actions to resolve those issues. For more
information, see AppDisks.
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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.142
You can also enable/disable and configure this feature later in Studio. For more information, see App-V.
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 Microsoft System Center Configuration Manager.
When you create a Remote PC Access Site:
If you're using the Wake on LAN feature, specify the Microsoft System Center Configuration Manager address,
credential, and connection information on the Power Management page.
Specify users or user groups on the Users page. T here 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 accounts, and then click Add
machine accounts. Click Add OUs. Select the domain and Organizational Units, and indicate whether to include items
in subfolders. Click Add OUs.
When you create a Remote PC Access Site, a machine catalog named Remote PC User Machine Accounts is created
automatically. T he catalog contains all the machine accounts you added in the Site creation wizard. A Delivery Group
named Remote PC User Desktops is created automatically. T he group contains all the users and user groups you added.
Summary
T he last page of the Site creation wizard summarizes 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 navigation pane. T hen
click Test site in the center pane. You can view an HT ML report of the Site test results.
T he site test functionality might fail for a Controller installed on Windows Server 2016. T he 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.
Troubleshoot
After configuring the Site, you can install Studio and add it through the MMC as a snap-in on a remote machine. If you later
attempt to remove that snap-in, the MMC might stop responding. As a workaround, restart the MMC.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.143
Create machine catalogs
Nov 28 , 20 17
Collections of physical or virtual machines are managed as a single entity called a machine catalog. All the machines in a
catalog have the same type of operating system: server or desktop. A catalog containing Server OS machines can contain
either Windows or Linux machines, not both.
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.
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 Provisioning Services (PVS). Or, you can use your own tools to provide machines.
If you use PVS to create machines, see the Provisioning Services documentation for instructions.
If you use MCS to provision VMs, you provide a master image (or snapshot) to create identical VMs in the catalog.
Before you create the catalog, you first use hypervisor or cloud service tools to create and configure the master image.
T his process includes installing a Virtual Delivery Agent (VDA) on the image. T hen you create the machine catalog in
Studio. You select that image (or a snapshot of an image), specify the number of VMs to create in the catalog, and
configure additional information.
If your machines are already available (so you do not need master images), 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 (VMT emplates),
rather than an image or a snapshot.
When using MCS or PVS 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. You can run the tests at any time from Studio.
RDS license check
Creation of a machine catalog containing Windows Server OS machines includes an automatic check for valid Microsoft
RDS licenses. Studio searches the catalog for a powered-on and registered machine to perform the check on.
If a powered-on and registered machine cannot be found, a warning is displayed, explaining that the RDS licensing check
could not be performed.
If a machine is found and an error is detected, Studio displays a warning message for the catalog containing the
detected issue. T o remove an RDS license warning from a catalog (so that it no longer appears in the Studio display),
select the catalog and then click Remove RDS license warning in the Actions pane. When prompted, confirm the
action.
VDA registration
A VDA must be registered with a Delivery Controller (for on-premises deployments) or Cloud Connector (for Citrix Cloud
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.144
deployments) to be considered when launching brokered sessions. Unregistered VDAs can result in underutilization of
otherwise available resources. T here are a variety of reasons a VDA might not be registered, many of which an
administrator can troubleshoot. Studio provides troubleshooting information in the catalog creation wizard, and after you
add machines from a catalog to a Delivery Group.
In the catalog creation wizard, after you add existing machines, 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, you can either remove that machine (using the Remove button), or add
the machine. For example, if a message indicates that information could not be obtained about a machine (perhaps
because it had never registered), you might choose to add the machine anyway.
For messages about functional level, see VDA versions and functional levels.
For more information about VDA registration troubleshooting, see CT X136668.
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:
T he full copy of the snapshot (noted above), 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. T his 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. T he
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.
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.
Prepare a master image on the hypervisor or cloud
service
Tip: For information about creating connections to hypervisors and cloud providers, see Connections and resources.
T he master image contains the operating system, non-virtualized applications, VDA, and other software.
Good to know:
A master image might also be known as a clone image, golden image, base VM, or base image. Host vendors and cloud
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.145
service providers may use different terms.
When using PVS, you can use a master image or a physical computer as the master target device. PVS uses different
terminology than MCS to refer to images; see the Provisioning Services documentation for details.
Ensure that the hypervisor or cloud service 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. T hat 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 re-arm Microsoft
Windows or Microsoft Office. If your deployment includes a 5.x VDA with a XenServer 6.0.2 host, see CT X128580.
Install and configure the following software on the master image:
Integration tools for your hypervisor (such as XenServer T ools, 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.
T hird-party tools as needed, such as anti-virus software or electronic software distribution agents. Configure services
with settings that are appropriate for users and the machine type (such as updating features).
T hird-party applications that you are not virtualizing. Citrix recommends virtualizing applications. 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. T he App-V client is available
from Microsoft.
When using MCS, if you localize Microsoft Windows, install the locales and language packs. During provisioning, when
a snapshot is created, the provisioned VMs use the installed locales and language packs.
Important: If you are using PVS 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 number of vCPUs when creating a catalog using Studio. Configure the amount
of hard disk space needed for desktops and applications. T hat 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 templates 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 PVS, create a VHD file for the vDisk from your master target device before you join the master target device
to a domain. See the Provisioning Services documentation for details.
5. If you are not using MCS, join the master image to the domain where applications and desktops 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. T he 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 so that it can be identified later. If you
specify a master image rather than a snapshot when creating a catalog, Studio creates a snapshot, but you cannot
name it.
Prepare a master image f or GPU-capable machines on XenServer
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.146
When using XenServer for your hosting infrastructure, GPU-capable machines require a dedicated master image. T hose 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 XenServer T ools and NVIDIA drivers.
5. T urn off 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.
Create a machine catalog using Studio
Before starting the catalog creation wizard, review this section to learn about the choices you make and information you
supply.
Important: 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.
T hen select Create Machine Catalog in the Actions pane.
T he wizard walks you through the items described below. T he wizard pages you see may differ, depending on the selections
you make.
Operating system
Each catalog contains machines of only one type:
Server OS: A Server OS catalog provides hosted shared desktops and applications. T he 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.)
Desktop OS: A Desktop OS catalog provides VDI desktops and applications that can be assigned 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
T his page does not appear when you are creating Remote PC Access catalogs.
T he Machine Management page indicates how machines are managed and which tool you use to deploy machines.
Choose whether or not machines in the catalog will be power managed through Studio.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.147
Machines are power managed through Studio or provisioned through a cloud environment, for example, VMs or blade
PCs. T his option is available only if you already configured a connection to a hypervisor or cloud service.
Machines are not power managed through Studio, for example, physical machines.
If you indicated that machines are power managed through Studio or provisioned through a cloud environment, choose
which tool to use to create VMs.
Citrix Machine Creation Services (MCS) – Uses a master image to create and manage virtual machines. Machine
catalogs in cloud environments use MCS. MCS is not available for physical machines.
Citrix Provisioning Services (PVS) – Manages target devices as a device collection. A PVS vDisk imaged from a master
target device delivers desktops and applications. T his option is not available for cloud deployments.
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 ensure that the machines in the catalog are
consistent.
Desktop types (desktop experience)
T his page appears only when you are creating a catalog containing Desktop OS machines.
T he 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 PVS to provision the machines, you can configure how user changes to the
desktop are handled:
Save user changes to the desktop on a separate Personal vDisk.
Save user changes to the desktop on the local disk.
Discard user changes and clear the virtual desktop when the user logs off.
Master image
T his page appears only when you are using MCS to create VMs.
Select the connection to the host hypervisor or cloud service, and then select the snapshot or VM created earlier. If you are
creating the first catalog, the only available connection will be the one you configured when you created the Site.
Remember:
When you are using MCS or PVS, 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 installed. 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.
Cloud platf orm and service environments
When you are using a cloud service or platform to host VMs (such as Azure Resource Manager, Nutanix, or Amazon Web
Services), the catalog creation wizard may contain additional pages specific to that host.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.148
For details, see Where to find information about connection types.
Device Collection
T his page appears only when using PVS to create VMs. It displays the device collections and the devices that have not
already been added to catalogs.
Select the device collections to use. See the Provisioning Services documentation for details.
Machines
T his page does not appear when you are creating Remote PC Access catalogs.
T he title of this page depends on what you selected on the Machine Management page: Machines, Virtual Machines, or
VMs and users.
When using MCS to create machines:
Specify how many virtual machines to create.
Choose the amount of memory (in MB) each VM will have.
Important: Each created VM will have a hard disk. Its size is set in the master image; you cannot change the hard disk
size in the catalog.
If you indicated on the Desktop Experience page that user changes to static desktops should be saved on a separate
Personal vDisk, specify the vDisk size in gigabytes and the drive letter.
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 personal vDisks, you can configure a cache to be used for
temporary data on each machine. See Configure cache for temporary data.
When using PVS to create machines:
T he 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 to provide machines:
Add (or import a list of) Active Directory machine account names. You can change the Active Directory account name
for a VM after you add/import it. If you specified static machines on the Desktop Experience wizard 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 wizard page.
When using PVS or other tools (but not MCS):
An icon and tooltip for each machine added (or imported, or from a PVS device collection) 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
T he copy mode you specify on the Machines page determines whether MCS creates thin (fast copy) or thick (full copy)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.149
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 may 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 will not be able to register.
A drop-down near the bottom of the Machines (or Devices) page allows you to select the minimum VDA level that will
successfully register; 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 XenApp and XenDesktop 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 XenApp and XenDesktop 7.15 LT SR contains a 7.15 VDA, the default
functional level ("7.9 .or later") remains the most current. T herefore, after installing or upgrading components from
7.9-7.14 to 7.15 LT SR, you do not need to change the default functional level.
In Citrix Cloud deployments, Studio uses a default functional level that can be earlier than the most current.
T he 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, but be aware that 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; however, that will prevent 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 Desktop OS catalog, or adding a Desktop OS machine originally created for random
allocation to a catalog of static machines.
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.
To enable the caching of temporary data, the VDA on each machine in the catalog must be minimum version 7.9.
You specify whether temporary data uses shared or local storage when you create the connection that the catalog uses;
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.150
for details, see Connections and resources. Enabling and configuring the temporary cache in the catalog includes two check
boxes and values: Memory allocated to cache (MB) and Disk cache size (GB). T he default values differ according to the
connection type. Generally, the default values are sufficient for most cases; however, take into account the space needed
for:
T emporary data files created by Windows itself, including the Windows page file.
User profile data.
ShareFile data that is synced to users' sessions.
Data that may be created or copied by a session user or any applications users may install inside the session.
Windows will not allow a session to use an amount of cache disk that is significantly 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.
If you enable the Disk cache size check box, temporary data is initially written to the memory cache. When the memory
cache reaches its configured limit (the Memory allocated to cache value), the oldest data is moved to the temporary data
cache disk.
T he memory cache is part of the total amount of memory on each machine; therefore, if you enable the Memory
allocated to cache check box, consider increasing the total amount of memory on each machine.
If you clear the Memory allocated to cache check box and leave the Disk cache size check box enabled, temporary data
is written directly to the cache disk, using a minimal amount of memory cache.
Changing the Disk cache size from its default value can affect performance. T he size must match user requirements and
the load placed on the machine.
Important: If the disk cache runs out of space, the user's session becomes unusable.
If you clear the Disk cache size check box, no cache disk will be created. In this case, specify a Memory allocated to
cache value that is large enough to hold all of the temporary data; this is feasible only if large amounts of RAM are
available for allocation to each VM.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.151
If you clear both check boxes, temporary data is not cached; it is written to the difference disk (located in the OS storage)
for each VM. (T his is the provisioning action in releases earlier than 7.9.)
Do not enable caching if you intend to use this catalog to create AppDisks.
You cannot change the cache values in a machine catalog after it is created.
Network Interf ace Cards (NICs)
T his page does not appear when you are creating Remote PC Access catalogs.
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
T his page appears only when creating Remote PC Access catalogs.
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 configured yet, you can create that connection
later and then edit the machine catalog to update the power management settings.
Computer accounts
T his page appears only when using MCS to create VMs.
Each machine in the catalog must have a corresponding Active Directory computer account. Indicate whether to create
new accounts or use existing accounts, and the location for those accounts.
If you create new accounts, you must have access to a domain administrator account for the domain where the
machines will reside.
Specify the account naming scheme for the machines that will be created, using hash marks to indicate where
sequential numbers or letters will 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 PCSales-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. T he imported file content must use the format:
[ADComputerAccount]
ADcomputeraccountname.domain
...
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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.152
For catalogs containing physical machines or existing machines, select or import existing accounts and assign each machine
to both an Active Directory computer account and to a user account.
For machines created with PVS, computer accounts for target devices are managed differently; see the Provisioning
Services documentation.
Summary, name, and description
On the Summary page of the wizard, review the settings you specified. Enter a name and description for the catalog; this
information appears in Studio.
After reviewing the information you specified, click Finish to start the catalog creation.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.153
Manage machine catalogs
Nov 28 , 20 17
In this article:
Introduction
Add machines to a machine catalog
Delete machines from a machine catalog
Change a machine catalog description or change Remote PC Access settings
Rename a machine catalog
Move a machine catalog to another zone
Delete a machine catalog
Manage Active Directory computer accounts in a machine catalog
Update a machine catalog
Upgrade a machine catalog
Introduction
You can add or remove machines from a machine catalog, as well as 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, anti-virus software updates,
operating system upgrades, or configuration changes.
For catalogs containing pooled random machines created using Machine Creation Services (MCS), you can maintain
machines by updating the master image used in the catalog and then updating the machines. T his enables you to
efficiently update large numbers of user machines. For machines created using Provisioning Services, updates to
machines are propagated through the vDisk. See the Provisioning Services documentation for details.
For catalogs containing static, permanently assigned machines, and for Remote PC Access Machine catalogs, you
manage updates to users' machines outside of Studio, either individually or collectively using third-party software
distribution tools.
For information about creating and managing connections to host hypervisors and cloud services, see Connections and
resources.
TIP: For machines with "Power State Unknown" status, see CT X131267 for guidance.
Add machines to a machine catalog
Before you start:
Make sure the virtualization host (hypervisor or cloud service provider) has sufficient processors, memory, and storage to
accommodate 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.154
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 will be created. Specify an account naming scheme, using hash marks to indicate where
sequential numbers or letters will 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 PCSales-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, 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.
T he machines are created as a background process, and can take a lot of time when creating a large number of machines.
Machine creation continues even if you close Studio.
Delete machines from a machine 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. T urning on maintenance mode will stop new connections from being made to a machine.
Machines are powered off.
To delete machines from a catalog:
1. Select Machine Catalogs in the Studio navigation pane.
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 whether the Active
Directory accounts for those machines should be retained, disabled, or deleted.
Change a machine catalog description or change
Remote PC Access settings
1. Select Machine Catalogs in the Studio navigation pane.
2. Select a catalog and then select Edit Machine Catalog in the Actions pane.
3. (Remote PC Access catalogs only) On the Power Management page, you can change the power management settings
and select a power management connection. On the Organizational Units page, add or remove Active Directory OUs.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.155
4. On the Description page, change the catalog description.
NOTE: For Remote PC Access catalogs in a Citrix Cloud XenApp and XenDesktop Service environment, follow the guidance
in CT X220737.
Rename a machine catalog
1. Select Machine Catalogs in the Studio navigation pane.
2. Select a catalog and then select Rename Machine Catalog in the Actions pane.
3. Enter the new name.
Move a machine catalog to a different zone
If your deployment has more than one zone, you can move a catalog from one zone to another.
Caution: Moving a catalog to a different zone than the hypervisor or cloud service containing the VMs in that catalog can
affect performance.
1. Select Machine Catalogs in the Studio navigation pane.
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 machine 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.
T he catalog is not associated a Delivery Group. In other words, the Delivery Group does not contain machines from the
catalog.
To delete a catalog:
1. Select Machine Catalogs in the Studio navigation pane.
2. Select a catalog and then select Delete Machine Catalog in the Actions pane.
3. Indicate whether the machines in the catalog should be deleted. If you choose to delete the machines, indicate whether
the Active Directory computer accounts for those machines should be retained, disabled, or deleted.
Manage Active Directory computer accounts in a
machine catalog
To manage Active Directory accounts in a machine catalog, you can:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.156
Free unused machine accounts by removing Active Directory computer accounts from Desktop OS and Server OS
catalogs. T hose 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:
1. Select Machine Catalogs in the Studio navigation pane.
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 accounts. You might reset passwords if you do
not know the current account passwords; you must have permission to perform a password reset. If you enter a
password, the password will be changed on the accounts as they are imported. If you delete an account, choose
whether the account in Active Directory should be kept, disabled, or deleted.
Note: You can also indicate whether Active Directory accounts should be retained, disabled, or deleted when you remove
machines from a catalog or delete a catalog.
Update a machine catalog
Citrix recommends that you save copies or snapshots of master images before you update the machines in the catalog.
T he database keeps an historical record of the master images used with each machine catalog. You can roll back (revert)
machines in a catalog to use the previous version of the master image if users encounter problems with updates you
deployed to their desktops, thereby minimizing user downtime. Do not delete, move, or rename master images; otherwise,
you will not be able to revert a catalog to use them.
For catalogs that use Provisioning Services, you must publish a new vDisk to apply changes to the catalog. For details, see
the Provisioning Services documentation.
After a machine is updated, it restarts automatically.
Update or create a new master image
Tip: for information about managing connections, see Connections and resources.
Before you update the Machine Catalog, either update an existing master image or create a new one on your host
hypervisor.
1. On your hypervisor or cloud service provider, take a snapshot of the current VM and give the snapshot a meaningful
name. T his 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. If the master image uses a personal vDisk, update the inventory.
5. For WIndows 10 machines, see the optmization resources linked in Prepare to install.
6. Power off the VM.
7. T ake a snapshot of the VM, and give the snapshot a meaningful name that will be recognized when the catalog is
updated in Studio. Although Studio can create a snapshot, Citrix recommends that you create a snapshot using the
hypervisor management console, and then select that snapshot in Studio. T his enables you to provide a meaningful
name and description rather than an automatically generated name. For GPU master images, you can change the master
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.157
image only through the XenServer XenCenter console.
Update the catalog
To prepare and roll out the update to all machines in a catalog:
1. Select Machine Catalogs in the Studio navigation pane.
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 will be updated with the new master
image: on the next shutdown or immediately. See below for details.
5. Verify the information on the Summary page and then click Finish. Each machine restarts automatically after it is
updated.
Tip: If you are updating a catalog using the PowerShell SDK directly, rather than Studio, you can specify a hypervisor
template (VMTemplates), as an alternative to an image or a snapshot of an image.
Rollout strategy
Updating the image on the next shutdown is provided when you are using the Citrix Connector for System Center
Configuration Manager.
If you choose to update the image immediately, configure a distribution time and notifications.
Distribution time: You can choose to update all machines at the same time, or specify the total length of time it should
take to begin updating all machines in the catalog. An internal algorithm determines when each machine is updated and
restarted during that interval.
Notif ication: In the left notification dropdown, choose whether to display a notification message on the machines
before an update begins. By default, no message is displayed. If you choose to display a message 15 minutes before the
update begins, you can choose (in the right dropdown) 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, calculated by an
internal algorithm.
Roll back an update
After you roll out an updated/new master image, you can roll it back. T his 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 will no longer be available. As with the rollout, rolling back a machine includes a
restart.
1. Select Machine Catalogs in the Studio navigation pane.
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 above for the rollout operation.
T he rollback is applied only to machines that need to be reverted. For machines that have not been updated with the
new/updated master image (for example, machines with users who have not logged off), users do not receive notification
messages and are not forced to log off.
Upgrade a machine catalog or revert an upgrade
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.158
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 Provisioning Services, upgrade the VDA version in the Provisioning Services console.
Start the upgraded machines so that they register with the Controller. T his lets Studio determine that the machines in
the catalog need upgrading.
To upgrade a catalog:
1. Select Machine Catalogs in the Studio navigation pane.
2. Select the catalog. T he Details tab in the lower pane displays version information.
3. Select Upgrade Catalog. If Studio detects that the catalog needs upgrading, it displays a message. 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.159
Create Delivery Groups
Nov 28 , 20 17
A Delivery Group is a collection of machines selected from one or more Machine Catalogs. T he Delivery Group specifies
which users can use those machines, plus the applications and/or 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. T here 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, but haven't yet created a Delivery Group, Studio will guide you to the
correct starting place to create a Delivery Group. If you have already created a Delivery Group and want to create
another, select Delivery Groups in the Studio navigation pane and then select Create Delivery Group in the Actions
pane.
2. T he Create Delivery Group wizard launches with an Introduction page, which you can remove from future launches of
this wizard.
3. T he wizard then guides you through the pages described below. When you are done with each page, click Next until you
reach the final page.
Machines
Select a Machine 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 Machine Catalog.
A Machine Catalog can be specified in more than one Delivery Group; however, 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 (Server OS, Desktop 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, and then upgrade Machine
Catalogs and Delivery Groups as needed. When creating a Delivery Group, if you select machines that have different VDA
versions installed, the Delivery Group will be compatible with the earliest VDA version. (T his is called the group’s functional
level.) For example, if one of the machines you select has VDA version 7.1 installed and other machines have the current
version, all machines in the group can use only those features that were supported in VDA 7.1. T his means that some
features that require later VDA versions might not be available in that Delivery Group. For example, to use the AppDisks
feature, the VDAs (and therefore the group's functional level) must be a minimum version 7.8.
Each machine in a Remote PC Access Machine 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.160
Delivery type
T his page appears only if you chose a Machine Catalog containing static (assigned) desktop OS machines. Choose either
Applications or Desktops on the Delivery Type page; you cannot enable both.
(If you selected machines from a Server OS or Desktop OS random (pooled) catalog, the delivery type is assumed to be
applications and desktops: you can deliver applications, desktops, or both.
AppDisks
To add an AppDisk, click Add. T he Select AppDisks dialog box lists available AppDisks in the left column. T he right column
lists the applications on the AppDisk. (Selecting the Applications tab above the right column lists applications in a format
similar to a Start menu; selecting the Installed packages tab lists applications in a format similar to the Programs and
Features list.)
Select one or more checkboxes.
For more information, see the AppDisks article.
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 entitlement policy rule
includes everyone; see the PowerShell SDK BrokerAppEntitlementPolicyRule cmdlets for details.
Application Groups (if configured).
Delivery Groups.
Applications.
T he 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 restricing 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 applications specified in the
Delivery Group.
(If Application Groups are configured) Configure the Application Group user list to allow members 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
T here 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.161
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 Receiver. (For Delivery Groups containing
Desktop OS machines, you can import user data (a list of users) later by editing the Delivery Group.)
Unauthenticated (anonymous)
For Delivery Groups containing Server OS machines, you can allow users to access applications and desktops without
presenting credentials to StoreFront or Citrix Receiver. 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 enabled, you must have an unauthenticated
StoreFront store.
Unauthenticated user accounts are created on demand when a session is launched, and 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.
T he following table describes your choices on the Users page:
Enable access f or
Add/assign users and
Enable the "Give access to unauthenticated
user groups?
users" check box?
Only authenticated users
Yes
No
Only unauthenticated users
No
Yes
Both authenticated and
Yes
Yes
unauthenticated users
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 already 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.162
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 will see duplicate names in Receiver.
Click the Add dropdown to display the application sources.
From Start menu: Applications that are discovered on a machine created from the master image 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 def ined: 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, perhaps in another Delivery Group. 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.
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 the App-V article.
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 Machine Catalog.
Desktops (or Desktop Assignment Rules)
T he title of this page depends on the Machine Catalog you chose earlier in the wizard:
If you chose a Machine Catalog containing pooled machines, this page is titled Desktops.
If you chose a Machine Catalog containing assigned machines and specified "Desktops" on the Delivery T ype page, this
page is titled Desktop User Assignments.
If you chose a Machine Catalog containing assigned machines and specified "Applications" on the Delivery T ype 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 Receiver.
T o add a tag restriction to a desktop, select Restrict launches to machines with this tag and then select the tag
from the dropdown. (See the T ags article for more information.)
Using the radio buttons, indicate who can launch a desktop (for groups with pooled machines) or who will be assigned a
machine when they launch the desktop (for groups with assigned machines). T he 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. T his 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.
Summary
Enter a name for the Delivery Group. You can also (optionally) enter a description, which will appear in Receiver and in Studio.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.163
Review the summary information and then click Finish. If you did not select any applications or specify any desktops to
deliver, you are asked if you want to continue.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.164
Manage Delivery Groups
Nov 28 , 20 17
In this article:
Introduction
Change user settings in a Delivery Group
Add or remove users in a Delivery Group
Change the delivery type of a Delivery Group
Change StoreFront addresses
Add, change, or remove a tag restriction for a desktop
Upgrade a Delivery Group or revert an upgrade
Manage Remote PC Access Delivery Groups
Shut down and restart machines in a Delivery Group
Power manage machines in a Delivery Group
Create a restart schedule for machines in a Delivery Group
Create multiple restart schedules for machines in a Delivery Group
Prevent users from connecting to a machine (maintenance mode) in a Delivery Group
Change assignments of machines to users in a Delivery Group
Change the maximum number of machines per user in a Delivery Group
Load manage machines in Delivery Groups
Remove a machine from a Delivery Group
Restrict access to machines in a Delivery Group
Update a machine in a Delivery Group
Log off or disconnect a session, or send a message to Delivery Group users
Configure session prelaunch and session linger
Introduction
T his article describes the procedures for managing Delivery Groups. 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.
See Applications for information about managing applications in Delivery Groups, including how to add and remove
applications in a Delivery Group, and change application properties.
Managing Delivery Groups requires the Delegated Administration permissions of the Delivery Group Administrator built-in
role. See Delegated Administration for details.
Tips:
In the Studio display for a Delivery Group, the "Installed VDA version" in the Details pane might differ from the actual
version installed on the machines. T he machine's Windows Programs and Features display shows the actual VDA version.
For machines with "Power State Unknown" status, see CT X131267 for guidance.
VDA registration with a Delivery Controller
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.165
VDAs that are not registered with a Delivery Controller are not considered when launching brokered sessions, which results
in underutilization of otherwise available resources. T here are various reasons a VDA might not be registered, many of which
an administrator can troubleshoot. Studio provides troubleshooting information in the catalog creation wizard, and after
you add a catalog to a Delivery Group.
After you create a Delivery Group, Studio displays details about machines associated with that group. T he details pane for
a Delivery Group indicates the number of machines that should be registered but are not. In other words, there might be
one or more machines that are powered on and not in maintenance mode, but are not currently registered with a
Controller. When viewing 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 more information about VDA registration troubleshooting, see CT X136668.
Change user settings in a Delivery Group
T he name of this page may appear as either User Settings or Basic Settings.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the User Settings (or Basic Settings) page, change any of the settings in the following table.
4. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Setting
Description
Description
T he text that StoreFront uses and that users see.
Enable Delivery Group
Whether or not the Delivery Group is enabled.
T ime zone
Enable Secure ICA
Secures communications to and from machines in the Delivery Group using SecureICA, which
encrypts the ICA protocol (default level is 128-bit; the level can be changed using the SDK).
Citrix recommends using additional encryption methods such as T LS 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 the Users section in the Create Delivery Groups article.
1. Select Delivery Groups in the Studio navigation pane.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.166
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the Users page, to add users, click Add, and then specify the users you want to add. T o remove users, select one or
more users and then click Remove. You can also select/clear the check box that enables or disables access by
unauthenticated users.
4. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Import or export user lists
For Delivery Groups containing physical Desktop 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. T he .csv file can contain data from a previous
product version.
T he 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. T he ADComputerAccount entries can be common names, IP addresses, distinguished names, or domain and computer
name pairs.
To import or export user information:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a Delivery Group, and then select Edit Delivery Group in the Actions pane.
3. On the Machine Allocation page, select Import list or Export list, and then browse to the file location.
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 the delivery type of a Delivery Group
T he delivery type indicates what the group can deliver: applications, desktops, or both.
Before changing an application only or desktops and applications type to a desktops only type, delete all applications
from the group.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select 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
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the StoreFront page, select or add StoreFront URLs that will be used by the Citrix Receiver that is installed on each
machine in the Delivery Group.
4. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.167
You can also specify StoreFront server address by selecting Configuration > StoreFront in the Studio navigation pane.
Add, change, or remove a tag restriction for a desktop
Important: Adding, changing, and removing tag restrictions can have unanticipated effects on which desktops are
considered for launch. Be sure to review the considerations and cautions in the Tags article.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the Desktops page, select the desktop and click Edit.
4. T o add a tag restriction, select Restrict launches to machines with the tag and then select the tag.
5. T o change or remove a tag restriction, either select a different tag or remove the tag restriction entirely by clearing
Restrict launches to machines with this tag.
6. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Upgrade a Delivery Group or revert an upgrade
Upgrade a Delivery Group after you upgrade the 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 Provisioning Services, upgrade the VDA version in the Provisioning Services console.
Start the machines containing the upgraded VDA so that they can register with a Delivery Controller. T his process tells
Studio what needs upgrading in the Delivery Group.
If you must continue to use earlier VDA versions, newer product features may not be available. For more information, see
the Upgrade articles.
To upgrade a Delivery Group:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Upgrade Delivery Group in the Actions pane. T he Upgrade Delivery Group action
appears only if Studio detects upgraded VDAs.
Before starting the upgrade process, Studio tells 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
selecting Undo in the Actions pane.
Manage Remote PC Access Delivery Groups
If a machine in a Remote PC Access machine catalog is not assigned to a user, Studio temporarily assigns the machine to a
Delivery Group associated with that catalog. T his temporary assignment enables the machine to be assigned to a user later.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.168
T he Delivery Group-to-machine catalog association has a priority value. Priority determines which Delivery Group that
machine is assigned to 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. You can set this priority value using the PowerShell SDK.
When first created, Remote PC Access machine catalogs are associated with a Delivery Group. T his means that machine
accounts or Organizational Units added to the catalog later can be added to the Delivery Group. T his association can be
switched off or on.
To add or remove a Remote PC Access machine catalog association with a Delivery Group:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a Remote PC Access group.
3. In the Details section, select the Machine Catalogs tab and then select a Remote PC Access catalog.
4. T o add or restore an association, select Add Desktops. T o remove an association, select Remove Association.
Shut down and restart machines in a Delivery Group
T his procedure is not supported for Remote PC Access machines.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select View Machines in the Actions pane.
3. Select the machine and then select one of the following in the Actions pane (some options may not be available,
depending on the machine state):
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 Windows attempts to
install updates during the shutdown, there is a risk that the machine will be powered off before the updates finish.
Citrix recommends that you prevent Desktop 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; see the Connections and resources article.
Power manage machines in a Delivery Group
You can power manage only virtual Desktop OS machines, not physical ones (including Remote PC Access machines).
Desktop OS machines with GPU capabilities cannot be suspended, so power-off operations fail. For Server OS machines,
you can create a restart schedule, which is also described in this article.
In Delivery Groups containing pooled machines, virtual Desktop OS machines can be in one of the following states:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.169
Randomly allocated and in use
Unallocated and unconnected
In Delivery Groups containing static machines, virtual Desktop 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 unallocated machines. Initially, all
machines are unallocated (except for those manually allocated 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 buf f ers: For pooled Delivery Groups and static Delivery Groups with unallocated machines, 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. T he 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 additional standby set of unallocated machines that are turned on when the number of machines in the pool
falls below a threshold that 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 disconnected for a specified
amount of time. For examples, machines will suspend automatically outside of office hours if users have been disconnected
for at least 10 minutes. Random machines or machines with personal vDisks automatically shut down when users log off,
unless you configure the ShutdownDesktopsAfterUse Delivery Group property in the SDK.
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. T he 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.
To power manage virtual Desktop OS machines:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group, and then select Edit Delivery Group in the Actions pane.
3. On the Power Management page, select Weekdays in the Power manage machines drop-down. By default, weekdays
are Monday to Friday.
4. For random Delivery Groups, in Machines to be powered on, select Edit and then specify the pool size during
weekdays. T hen, 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 machine in the Delivery Group, and
select Suspend. In During of f -peak hours > When disconnected, specify the delay before turning off any logged-off
machine in the Delivery Group, and select Shutdown. T his timer is not available for Delivery Groups with random
machines.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.170
7. Select Weekend in the Power manage machines drop-down, and then configure the peak hours and power state timers
for weekends.
8. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
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 CT X217289.
Create a restart schedule for machines in a Delivery
Group
Note: T his section describes how to configure a single restart schedule in Studio. Alternatively, you can use PowerShell to
configure multiple restart schedules for different subsets of machines in a Delivery Group. See the next section for details.
A restart schedule specifies when to periodically restart all the machines in a Delivery Group.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the Restart Schedule page, if you do not want to restart machines in the Delivery Group automatically, select the
No radio button and skip to the last step in this procedure. No restart schedule or rollout strategy will be configured. If a
schedule was previously configured, this selection cancels it.
4. If you do want to restart machines in the Delivery Group automatically, select the Yes radio button.
5. For Restart frequency, choose either Daily or the day of the week the restarts will occur.
6. For Begin restart at, using a 24-hour clock, specify the time of day to begin the restart.
7. For Restart duration, choose whether all machines should be started at the same time, or the total length of time to
begin restarting all machines in the Delivery Group. An internal algorithm determines when each machine is restarted
during that interval.
8. In the left Notif ication drop-down, 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 the Repeat notif ication drop-down) to repeat the message every five minutes after the
initial message. By default, the message is not repeated.
9. Enter the notification text in the Notif ication message box; there is no default text. If you want the message to
include the number of minutes before restart, include the variable %m% (for example: Warning: Your computer will be
automatically restarted in %m% minutes.) If you select a repeat notification interval and your message includes the %m%
placeholder, the value decrements by five minutes in each repeated message. Unless you chose to restart all machines at
the same time, the notification message displays on each machine in the Delivery Group at the appropriate time before
the restart, calculated by the internal algorithm.
10. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
You cannot perform an automated power-on or shutdown from Studio, only a restart.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.171
Create multiple restart schedules for machines in a
Delivery Group
You can use PowerShell cmdlets to create multiple restart schedules for machines in a Delivery Group. Each schedule can be
configured to affect only those machines in the group that have a specified tag. T his tag restriction functionality allows
you to easily create different restart schedules for different subsets of machines in one Delivery Group.
For example, let's say you use one Delivery Group for all machines in the company. You want to restart every machine at
least once every week (on Sunday night), but the machines used by the accounting team should be restarted daily. You can
set up a weekly schedule for all machines, and a daily schedule for just the machines used by the accounting team.
Schedule overlap
Multiple schedules might overlap. In the example above, the machines used by accounting are affected by both schedules,
and might be restarted twice on Sunday.
T he scheduling code is designed to avoid restarting the same machine more often than needed, but it cannot be
guaranteed. If both schedules coincide precisely in start and duration times, it is more likely that the machines will be
restarted only once. However, the more the schedules differ in start and/or duration times, the more likely two restarts will
occur. Also, the number of machines affected by the schedules can also influence the chances of an overlap. In the
example, the weekly schedule that restarts all machines could initiate restarts significantly faster than the daily schedule
(depending on the configured duration for each).
Requirements
Support for creating multiple restart schedules and using tag restrictions in a restart schedule is currently available only
through the PowerShell command line, using RebootScheduleV2 PowerShell cmdlets that are new in XenApp and
XenDesktop 7.12. (T hese are referred to as the "V2" cmdlets throughout this article.)
Using the V2 cmdlets requires:
Delivery Controller version 7.12 (minimum).
If you use the latest SDK plug-in with a Controller earlier than 7.12, any new schedules you create will not work as
intended.
In a mixed site (where some, but not all Controllers have been upgraded), the V2 cmdlets will not work until the
database is upgraded and at least one Controller has been upgraded and is being used (by specifying the –
adminaddress <controller> parameter with the V2 cmdlets).
Best practice: Do not create any new schedules until all Controllers in the site are upgraded.
PowerShell SDK snap-in provided with XenApp and XenDesktop 7.12 (minimum). After you install or upgrade your
components and site, run asnp Citrix.* to load the latest cmdlets.
Studio currently uses earlier V1 RebootSchedule PowerShell cmdlets, and will not display schedules that are created with
the V2 cmdlets.
After you create a restart schedule that uses a tag restriction, and then later use Studio to remove the tag from an
affected machine during a restart interval (cycle) or add the tag to additional machines during a restart cycle, those
changes will not take effect until the next restart cycle. (T he changes will not affect the current restart cycle.)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.172
PowerShell cmdlets
Use the following RebootScheduleV2 cmdlets from the command line to create multiple schedules and use tag restrictions
in the schedules.
New (V2) cmdlet
Replaces earlier (V1) cmdlet
New-BrokerRebootScheduleV2
New-BrokerRebootSchedule
Get-BrokerRebootScheduleV2
Get-BrokerRebootSchedule
Set- BrokerRebootScheduleV2
Set-BrokerRebootSchedule
Remove-BrokerRebootScheduleV2
Remove-BrokerRebootSchedule
Rename-BrokerRebootScheduleV2
-
For complete cmdlet syntax and parameter descriptions, enter Get-Help –f ull <cmdlet-name>.
Terminology reminder: In the PowerShell SDK, the DesktopGroup parameter identifies the Delivery Group.
If you're familiar with the Studio interface for creating a restart schedule, all of those parameters are available when using
the V2 cmdlet to create or update a schedule. Additionally, you can:
Restrict the schedule to machines that have a specified tag.
Specify an interval before sending the first warning message, during which no new sessions will be brokered to the
affected machines.
Configuration
If you configure a restart schedule that uses a tag restriction, you must also add (apply) that tag to the machines that you
want the schedule to affect. (For more information, see Tags.)
1. From Studio, select Delivery Groups in the navigation pane.
2. Select the Delivery Group containing the machines that will be affected by the schedule.
3. Select View Machines and then select the machines where you'll add a tag.
4. Select Manage Tags in the Actions pane.
5. If the tag already 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 T ags dialog box.
After creating and adding (applying) tags, use the – RestrictToTag parameter to specify the tag name when creating or
editing the schedule with the V2 cmdlet.
If you created a restart schedule with an earlier XenApp or XenDesktop version
Studio currently uses the V1 RebootSchedule cmdlets. If you have a restart schedule that was created before you
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.173
upgraded to 7.12 (minimum), you can continue to manage it in Studio with V1 cmdlets, but you cannot use Studio to add a
tag restriction to that schedule, or to create additional schedules (because Studio does not support the V2 cmdlets). As
long as you use the V1 cmdlets for your existing schedule, Studio will display correct information about the restart schedule.
Alternatively, you can edit your existing schedule from the command line, using the new V2 RebootSchedule cmdlets. When
using the new V2 cmdlets, you can use the tag restriction parameters in that schedule, and create additional restart
schedules. However, after you use V2 cmdlets to change your existing schedule, Studio will not display complete schedule
information (because it recognizes only V1 information). You cannot see whether a tag restriction is used, or the schedule's
name and description.
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 management tools.
When a Server OS machine is in maintenance mode, users can connect to existing sessions, but cannot start new
sessions.
When a Desktop OS machine (or a PC using Remote PC Access) is in maintenance mode, users cannot connect or
reconnect. Current connections remain connected until they disconnect or log off.
To turn maintenance mode on or off:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group.
3. T o turn on maintenance mode for all machines in the Delivery Group, select Turn On Maintenance Mode in the Actions
pane. T o turn on maintenance mode for one machine, select View Machines in the Actions pane. Select a machine, and
then select Turn On Maintenance Mode in the Actions pane.
4. T o turn maintenance mode off for one or all machines in a Delivery Group, follow the previous instructions, but select
Turn Of f Maintenance Mode in the Actions pane.
Windows Remote Desktop Connection (RDC) settings also affect whether a Server OS machine is in maintenance mode.
Maintenance mode is on when any of the following occur:
Maintenance mode is set to on, as described above.
RDC is set to Don’t allow connections to this computer.
RDC is not set to Don’t allow connections to this computer, and 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 that use that connection), or
for a machine catalog (which affects the machines in that catalog).
Change assignments of machines to users in a
Delivery Group
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.174
You can change the assignments of Desktop OS machines, not Server OS machines or machines created through
Provisioning Services.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group.
3. Select Edit Delivery Group in the Actions pane. On the Desktops or Desktop Assignment Rules page (only one of
those pages will be available, depending on the type of machine catalog the Delivery Group uses), specify the new users.
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 the maximum number of machines per user
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select Edit Delivery Group in the Actions pane.
3. On the Desktop Assignment Rules page, set the maximum desktops per user value.
4. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Load manage machines in Delivery Groups
You can load manage Server OS machines only.
Load Management measures the server load and determines which server to select under the current environment
conditions. T his selection is based on:
Server maintenance mode status: A Server OS machine is considered for load balancing only when maintenance mode is
off.
Server load index: Determines how likely a server delivering Server OS machines is to receive connections. T he index is a
combination of load evaluators: the number of sessions and the settings for performance metrics such as CPU, disk, and
memory use. You specify the load evaluators in load management policy settings.
You can monitor the load index in Director, Studio search, and the SDK.
In Studio, the Server Load Index column is hidden by default. To display it, select a machine, right-select a column heading
and then choose Select Column. In the Machine category, select Load Index.
In the SDK, use the Get-BrokerMachine cmdlet. For details, see CT X202150.
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 currently unavailable when they launch a session.
Concurrent logon tolerance policy setting: T he maximum number of concurrent requests to log on to the server. (T his
setting is equivalent to load throttling in XenApp versions earlier than 7.5.)
If 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.175
Remove a machine from a Delivery Group
Removing a machine deletes it from a Delivery Group but does not delete it from the machine catalog that the Delivery
Group uses. T herefore, 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.
Keep in mind that machines may contain personal data, so use caution before allocating the machine to another user. You
may want to reimage the machine.
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and the select View Machines in the Actions pane.
3. Make sure that the machine is shut down.
4. Select Remove f rom Delivery Group in the Actions pane.
You can also remove a machine from a Delivery Group through the connection the machine uses. For details, see
Connections and resources.
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 f or administrators using Delegated Administration scopes. You can create and assign a scope that
permits administrators to access all applications, and another scope that provides access to only certain applications. See
the Delegated Administration article for details.
Restrict access f or users through SmartAccess policy expressions that filter user connections made through
NetScaler Gateway.
1. Select Delivery Groups in the Studio navigation pane.
2. Select group and then select Edit Delivery Group in the Actions pane.
3. On the Access Policy page, select Connections through NetScaler Gateway.
4. T o choose a subset of those connections, select Connections meeting any of the f ollowing f ilters. T hen define the
NetScaler Gateway site, and add, edit, or remove the SmartAccess policy expressions for the allowed user access
scenarios. For details, see the NetScaler Gateway 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 f or users through 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, for a teaching lab on a subnet in the corporate network, to prevent access from that lab to a particular
Delivery Group, regardless of who is using the machines in the lab, use the following command: Set-BrokerAccessPolicy -
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.176
Name VPDesktops_Direct -ExcludedClientIPFilterEnabled $True You can 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 SetBrokerAccessPolicy script to VPDesktops_* applies the filter to both machines.
If you are connected using a web browser or with the unified Citrix Receiver user experience feature enabled in the store,
you cannot use a client name exclusion filter.
Update a machine in a Delivery Group
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select View Machines in the Action pane.
3. Select a machine and then select 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. T hen 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), and whether users will be notified of the restart, plus the message they will receive.
Log off or disconnect a session, or send a message to
Delivery Group users
1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then select View Machines in the Actions pane.
3. T o log a user off a session, select the session or desktop and select Log of f in the Actions pane. T he session closes and
the machine becomes available to other users, unless it is allocated to a specific user.
4. T o disconnect a session, select the session or desktop, and select Disconnect in the Actions pane. Applications continue
to run and the machine remains allocated to that user. T he user can reconnect to the same machine.
5. T o send a message to users, select the session, machine, or user, and then select Send message in the Actions pane.
Enter the message.
You can configure power state timers for Desktop OS machines to automatically handle unused sessions. See the Power
manage machines section for details.
Configure session prelaunch and session linger in a
Delivery Group
T hese features are supported on Server OS machines only.
T he 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.177
(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:
T he Delivery Group must support applications, and the machines must be running a VDA for Windows Server OS,
minimum version 7.6.
T hese features are supported only when using Citrix Receiver for Windows, and also require additional Citrix Receiver
configuration. For instructions, search for session prelaunch in the product documentation for your Citrix Receiver for
Windows version.
Note that Citrix Receiver for HT ML5 is not supported.
When using session prelaunch, if a user's machine is put into "suspend" or "hibernate" mode, prelaunch will not work
(regardless of session prelaunch settings). Users can lock their machines/sessions, but if a user logs off from Citrix
Receiver, 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 license, but only when connected. Unused prelaunched and lingering
sessions disconnect after 15 minutes by default. T his value can be configured in PowerShell (New/SetBrokerSessionPreLaunch 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 application 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 Receiver.
How long unused prelaunched and lingering sessions remain active
T here 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 will 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 cannot disable this timeout from Studio, but you can in the SDK (New/Set-BrokerSessionPreLaunch cmdlet). If
you disable the timeout, it will not appear in the Studio display for that Delivery Group or in the Edit Delivery Group
wizard.
Thresholds: Automatically ending prelaunched and lingering sessions based on server load ensures that sessions remain
open as long as possible, assuming server resources are available. Unused prelaunched and lingering sessions will not cause
denied connections because they will be 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 Delivery 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.)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.178
Servers with VDAs that have not registered with the Controller and servers in maintenance mode are considered fully
loaded. An unplanned outage causes prelaunch and lingering sessions end automatically to free capacity.
To enable session prelaunch
1. Select Delivery Groups in the Studio navigation pane.
2. Select a Delivery Group, and then click Edit Delivery Group in the Actions pane.
3. On the Application Prelaunch page, enable session prelaunch by choosing when sessions should launch:
When a user starts an application. T his is the default setting; session prelaunch is disabled.
When any user in the Delivery Group logs on to Citrix Receiver for Windows.
When anyone in a list of users and user groups logs on to Citrix Receiver for Windows. 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 settings 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 percentage (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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.179
To enable session linger
1. Select Delivery Groups in the Studio navigation pane.
2. Select a Delivery Group, and then click Edit Delivery Group in the Actions pane.
3. On the Application Lingering page, enable session linger by selecting the Keep sessions active until radio button.
4. Several settings affect how long a lingering session remains active if the user does not start another 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 percentage (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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.180
Create Application Groups
Nov 28 , 20 17
Introduction
Application Groups let you manage collections of applications. You can create Application Groups for applications shared
across different Delivery Groups or used by a subset of users within Delivery Groups. Application Groups are optional; they
offer an alternative to adding the same applications to multiple Delivery Groups. Delivery Groups can be associated with
more than one Application Group, and an Application Group can be associated with more than one Delivery Group.
Using Application Groups can provide application management and resource control advantages over using more Delivery
Groups:
T he 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 may be beneficial.
You can use the tag restriction feature to publish applications from an Application Group, considering 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 additional machines. A tag restriction can be
thought of as subdividing (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
T he following graphic shows a XenApp or XenDesktop deployment that includes Application Groups:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.181
In this configuration, applications are added to the Application Groups, not the Delivery Groups. T he Delivery Groups specify
which machines will be used. (Although not shown, the machines are in Machine Catalogs.)
Application Group 1 is associated with Delivery Group 1. T he applications in Application Group 1 can be accessed by the
users specified in Application Group 1, as long as they are also in the user list for Delivery Group 1. T his follows the guidance
that the user list for an Application Group should be a subset (a restriction) of the user lists for the associated Delivery
Groups. T he settings in Application Group 1 (such as application session sharing between Application Groups, associated
Delivery Groups) apply to applications and users in that group. T he settings in Delivery Group 1 (such as anonymous user
support) 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 can be assigned a
priority in Application Group 2, which indicates the order in which the Delivery Groups will be checked when an application is
launched. Delivery Groups with equal priority are load balanced. T he applications in Application Group 2 can be accessed by
the users specified in Application Group 2, as long as they are also in the user lists for Delivery Group 1 and Delivery Group 2.
Example 2:
T his simple layout uses tag restrictions to limit which machines will be considered for certain desktop and application
launches. T he 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).
T he Application Group was created with the "Orange" tag restriction, so each of its applications (Calculator and Notepad)
can be 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 the
Tags article.
Guidance and considerations
Citrix recommends adding applications to either Application Groups or Delivery Groups, but not both. Otherwise, the
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.182
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 the Manage Application Groups article.
By default, application session sharing between Application Groups is enabled; see Session sharing between Application
Groups below.
Citrix recommends that your Delivery Groups be upgraded to the current version. T his requires (1) upgrading VDAs on the
machines used in the Delivery Group, then (2) upgrading the Machine Catalogs containing those machines, and then (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 the Delegated Administration article for details.
T his article refers to "associating" an application with more than one Application Group to differentiate that action from
adding a new instance of that application from an available source. Similarly, Delivery Groups are associated with
Application Groups (and vice versa), rather than being additions or components of one another.
Session sharing with Application Groups
When application session sharing is enabled, all applications launch in the same application session. T his saves the costs
associated with launching additional application sessions, and allows the use of application features that involve the
clipboard, such as copy-paste operations. However, in some situations you may wish to turn off 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.
Example when enabling session sharing between Application Groups is helpful:
Application Group 1 contains Microsoft Office applications such as Word and Excel. Application 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 existing 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.
Example when disabling session sharing between Application Groups is helpful:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.183
You have 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.
You 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 between 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, and can still run other applications at the same time, but not in the same session. If the user launches one of
the different-versioned applications (that are in a different Application Group), or launches any application that is not
contained in an Application Group, then that application is launched in a new session.
IMPORTANT: T his 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 (providing that this complies with the session sharing restrictions described here).
You can only make prelaunched sessions available to Application Groups which have application session sharing allowed.
(Sessions which use the session linger feature are available to all Application Groups.) T hese 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 the Manage Application Groups article.
Disable session sharing within an Application Group
You can prevent application session sharing between applications which are in the same Application Group.
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. If session sharing is prohibited between applications in
that Application Group, when a user specified in it starts one application after another they launch in separate
sessions, and the user can move each to a separate monitor.
By default, application session sharing 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 the Manage
Application Groups article.
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. T he Create Application Group wizard launches with an Introduction page, which you can remove from future launches
of this wizard.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.184
3. T he wizard guides you through the pages described below. When you are done with each page, click Next until you
reach the Summary page.
Delivery Groups
All Delivery Groups are listed, with the number of machines each contains.
T he Compatible Delivery Groups list contains Delivery Groups you can select. Compatible Delivery Groups contain
random (not permanently or statically assigned) server or desktop OS machines.
T he Incompatible Delivery Groups list contains Delivery Groups you cannot select. Each entry explains why it is not
compatible, such as containing static 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 desktops only, if (1) the Delivery Group contains
shared machines and was created with an earlier XenDesktop 7.x version, and (2) you have Edit Delivery Group permission.
T he Delivery Group type is automatically converted to "desktops and applications" when the Create Application Group
wizard is committed.
Although you can create an Application Group that has no associated Delivery Groups – perhaps to organize applications or
to serve as storage for applications not currently in use – the Application Group cannot be used to deliver applications until
it specifies at least one Delivery Group. Additionally, you cannot add applications to the Application Group from the From
Start menu source if there are no Delivery Groups specified.
T he Delivery Groups you select specify the machines that will be 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 dropdown.
See the Tags article for full details.
Users
Specify who can use the applications in the Application Group. You can either allow all users and user groups in the Delivery
Groups you selected on the previous page, or select specific users and user groups from those Delivery Groups. If you
restrict use to users you specify, then only the users specified in the Delivery Group and the Application Group can access
the applications in this Application 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.
Where user lists are specified
Active Directory user lists are specified when you create or edit the following:
T he entitlement user list for the delivery group, which is not configured through Studio. By default, the application
entitlement policy rule includes everyone; see the PowerShell SDK BrokerAppEntitlementPolicyRule cmdlets for details.
T he Application Group user list.
T he Delivery Group user list.
T he Application visibility property.
T he list of users who can access an application through StoreFront is formed by the intersection of the above user lists. For
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.185
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 applications specified in the
Delivery Group.
Configure the Application Group user list to allow members of the Administration and Finance business unit to access
applications named A through L.
Configure application A’s properties to restrict its visibility to only Accounts Receivable staff in Administration and
Finance.
Applications
Good to know:
By default, new applications you add are placed in a folder named Applications. You can specify a different folder. If you
try to add an application and one with the same name already 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 will see duplicate names in Citrix Receiver.
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 dropdown to display the application sources.
Source
Description
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.
T his source cannot be selected if you (1) selected Application Groups that have no
associated Delivery Groups, (2) selected Application Groups with associated Delivery Groups
that contain no machines, or (3) selected 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.
T his source cannot be selected If the Site has no applications.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.186
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
checkboxes of applications to add, and then click OK. For more information, see the AppV article.
T his source cannot be selected (or might not appear) if App-V is not configured for the Site.
As noted, certain entries in the Add dropdown will not be 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.
Scopes
This page appears only if you have previously created a scope. By default, the All scope is selected. For more information, see the Delegated Administration article.
Summary
Enter a name for the Application Group. You can also (optionally) enter a description.
Review the summary information and then click Finish.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.187
Manage Application Groups
Nov 28 , 20 17
In this article:
Introduction
Enable or disable an Application Group
Enable or disable application session sharing between Application Groups
Disable application session sharing within an Application Group
Rename an Application Group
Add, remove, or change priority of Delivery Group associations with an Application Group
Add, change, or remove a tag restriction in an Application Group
Add or remove users in an Application Group
Change scopes in an Application Group
Delete an Application Group
Introduction
T his article describes the procedures for managing 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. Disabling 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. Similarly, if the application was explicitly added to
Delivery Groups associated with the Application Group (in addition to being added to 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 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 apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Enable or disable application session sharing between
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.188
Application Groups
Session sharing between Application Groups is enabled when you create an Application Group; you cannot change this
when you create the group. For more information about application session sharing, see Session sharing between
Application Groups.
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 session sharing between Application Groups check
box.
4. Click Apply to apply any changes you made and 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 Broker PowerShell SDK to configure Application Groups with
application session sharing disabled between the applications they contain. In some circumstances this may be desirable: for
example, you may want users to start non-seamless applications in full-size application windows on separate monitors. For
more information about application session sharing, see Session sharing with Application Groups.
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, if you launch Notepad, and there is a disconnected session with Notepad running, that session is reconnected
instead of creating a new one. If multiple suitable disconnected sessions are available, one of the sessions is chosen to
reconnect to, in a random but deterministic manner: if the situation reoccurs in the same circumstances, the same session is
chosen, but the session is not necessarily predictable otherwise.
You can use the Broker PowerShell SDK either to disable application session sharing for all applications in an existing
Application Group, or to create an Application Group with application session sharing disabled.
PowerShell cmdlet examples
To disable session sharing, use the Broker PowerShell cmdlets New-BrokerApplicationGroup or SetBrokerApplicationGroup 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 Application Group:
Set-BrokerApplicationGroup AppGR1 -SessionSharingEnabled $False ‑SingleAppPerSession $True
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.189
Notes
T o enable the SingleAppPerSession property you must set SessionSharingEnabled property to False. T he two properties
must not be enabled at the same time. T he SessionSharingEnabled parameter refers to sharing sessions between
Application Groups.
Application session sharing only works for applications which 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 having the option set to T rue, the other set to False) which results in unpredictable behavior.
Rename an Application Group
1. Select Applications in the Studio navigation pane.
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 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 desktops only, if (1) the Delivery Group contains
shared machines and was created with an earlier XenDesktop 7.x version, and (2) you have Edit Delivery Group permission.
T he Delivery Group type is automatically converted to "desktops and applications" when the Edit Application Group dialog is
committed.
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. Select the Delivery Groups page.
4. T o add Delivery Groups, click Add. Select the check boxes of available Delivery Groups. (Incompatible Delivery Groups
cannot be selected.) When you finish your selections, click OK.
5. T o remove Delivery Groups, select the check boxes of the groups you want to remove and then click Remove. Confirm
the deletion when prompted.
6. T o change the priority of Delivery Groups, select the checkbox 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 changes and close the
window.
Add, change, or remove a tag restriction in an
Application Group
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.190
Important: Adding, changing, and removing tag restrictions can have unanticipated effects on which machines are
considered for application launch. Be sure to review the considerations and cautions in the Tags article.
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. Select the Delivery Groups page.
4. T o add a tag restriction, select Restrict launches to machines with the tag and then select the tag from the
dropdown.
5. T o change or remove a tag restriction, either select a different tag from the dropdown or remove the tag restriction
entirely by clearing Restrict launches to machines with this tag.
6. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Add or remove users in an Application Group
For detailed information about users, see the Users section in the Create Application Groups article.
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. 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. T o add users, click Add, and then specify the
users you want to add. T o remove users, select one or more users and then click Remove.
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 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 the
Delegated Administration article.
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. Select the Scopes page. Select or clear the check box next to a scope.
4. Click Apply to apply any changes you made and keep the window open, or click OK to apply changes and close the
window.
Delete an Application Group
An application must be associated with at least one Delivery Group or Application Group. If your attempt to delete an
Application Group will result in one or more applications no longer belonging to a group, you will be warned that deleting
that group will also delete those applications. You can then confirm or cancel the deletion.
Deleting an application does not delete it from its original source, but if you want to make it available again, you must add
it again.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.191
1. Select Applications in the Studio navigation pane.
2. Select an Application Group in the middle pane and then select Delete Group in the Actions pane.
3. Confirm the deletion when prompted.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.192
Remote PC Access
Nov 28 , 20 17
Remote PC Access allows an end user to log on remotely from virtually anywhere to the physical Windows PC in the office.
T he Virtual Delivery Agent (VDA) is installed on the office PC; it registers with the Cloud Connector or Delivery Controller and
manages the HDX connection between the PC and the end user client devices. Remote PC Access supports a self-service
model; after you set up the whitelist of machines that users are permitted to access, those users can join their office PCs
themselves, without administrator intervention. T he Citrix Receiver running on their client device enables access to the
applications and data on the office PC from the Remote PC Access desktop session.
A user can have multiple desktops, including more than one physical PC or a combination of physical PCs and virtual
desktops.
Note: Sleep mode and hibernation mode are not supported for Remote PC Access. (For on-premises XenApp and
XenDesktop deployments: Remote PC Access is valid only for XenDesktop licenses; sessions consume licenses in the same
way as other XenDesktop sessions.)
Active Directory considerations
Before configuring the Remote PC Access deployment Site, set up your Organizational Units (OUs) and security groups and
then create user accounts.
If you modify Active Directory after a machine has been added to a machine catalog, Remote PC Access does not
reevaluate that assignment. You can manually reassign a machine to a different catalog, if needed.
If you move or delete OUs, those used for Remote PC Access can become out of date. VDAs might no longer be
associated with the most appropriate (or any) machine catalog or Delivery Group.
Machine catalog and Delivery Group considerations
A machine can be assigned to only one machine catalog and one Delivery Group at a time.
You can put machines in one or more Remote PC Access machine catalogs.
When choosing machine accounts for a catalog, select the lowest applicable OU to avoid potential conflicts with machines
in another catalog. For example, in the case of bank/officers/tellers, select tellers.
You can allocate all machines from one Remote PC Access machine catalog through one or more Delivery Groups. For
example, if one group of users requires certain policy settings and another group requires different settings, assigning the
users to different Delivery Groups enables you to filter the HDX policies according to each Delivery Group.
If your IT infrastructure assigns responsibility for servicing users based on geographic location, department, or some other
category, you can group machines and users accordingly to allow for delegated administration. Ensure that each
administrator has permissions for both the relevant catalogs and the corresponding Delivery Groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.193
Deployment considerations
You can create a Remote PC Access deployment and then add traditional Virtual Desktop Infrastructure (VDI) desktops or
applications later. You can also add Remote PC Access desktops to an existing VDI deployment.
Consider whether to enable the Windows Remote Assistance checkbox when you install the VDA on the office PC. T his
option allows help desk teams using Director to view and interact with a user sessions using Windows Remote Assistance.
Consider how you will deploy the VDA to each office PC. Citrix recommends using electronic software distribution such as
Active Directory scripts and Microsoft System Center Configuration Manager. T he installation media contains sample Active
Directory scripts.
Review the security considerations for Remote PC Access deployments.
Secure Boot for Remote PC Access is currently supported on Windows 10.
Each office PC must be domain-joined with a wired network connection.
Windows 7 Aero is supported on the office PC, but not required.
Connect the keyboard and mouse directly to the PC or laptop, not to the monitor or other components that can be turned
off. If you must connect input devices to components such as monitors, they should not be turned off.
If you are using smart cards, see Smart cards.
Remote PC Access can be used on most laptop computers. To improve accessibility and deliver the best connection
experience, configure the laptop power saving options to those of a desktop PC. For example:
Disable the hibernate feature.
Disable the sleep feature.
Set the close lid action to Do Nothing.
Set the press the power button action to Shut Down.
Disable video card energy saving features.
Disable network interface card energy saving features.
Disable battery saving technologies.
T he following are not supported for Remote PC Access devices:
Docking and undocking the laptop.
KVM switches or other components that can disconnect a session.
Hybrid PCs, including All-in-One and NVIDIA Optimus laptops and PCs.
Citrix supports Remote PC Access on Surface Pro devices with Windows 10. To improve accessibility and deliver the best
connection experience, configure the Surface device in a similar way to a desktop or laptop computer. For example:
Disable the hibernate or sleep feature
Use wired network connectivity
Always have the keyboard attached when initiating or reconnecting a session
Disable battery saving technologies
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.194
Install Citrix Receiver on each client device that remotely accesses the office PC.
Multiple users with remote access to the same office PC see the same icon in Citrix Receiver. When any user remotely logs
on to the PC, that resource appears as unavailable to other users.
By default, a remote user’s session is automatically disconnected when a local user initiates a session on that machine (by
pressing CT RL+AT L+DEL). To prevent this automatic action, add the following registry entry on the office PC, and then
restart the machine.
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 Registry Editor can be solved. Use Registry Editor
at your own risk. Be sure to back up the registry before you edit it.
HKLM\SOFT WARE\Citrix\PortICA\RemotePC "SasNotification"=dword:00000001
To further customize the behavior of this feature under HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\PortICA\RemotePC
RpcaMode (dword):
1 = T he remote user will always win if he does not respond to the messaging UI in the specified timeout period.
2 = T he local user will always win. If this setting is not specified, the remote user will always win by default.
RpcaT imeout (dword):
T he number of seconds given to the user before the type of mode to enforce is determined. If this setting is not
specified, the default value is 30 seconds. T he minimum value here should be 30 seconds. T he user must restart the
machine for these changes to take place.
When user wants to forcibly get the console access: T he local user can press Ctr+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 CT RL+ALT +DEL to log on to that PC while it is in use
by a remote user, the remote user receives a prompt asking whether or not to allow or deny the local user's connection.
Allowing the connection will disconnect the remote user's session.
Wake on LAN
NOTE: Wake on LAN is not supported with Remote PC Access in Citrix Cloud.
Remote PC Access supports Wake on LAN, which gives users the ability to turn on physical PCs remotely. T his 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, such as during weather events.
T he Remote PC Access Wake on LAN feature is supported on:
PCs that have the Wake on LAN option enabled in the BIOS. T his support includes wake-up proxy and raw magic
packets, and is available when using Microsoft System Cemter Configuration Manager (ConfigMgr) 2012, ConfigMgr
2012 R2, and ConfigMgr 2016.
PCs that support Intel Active Management T echnology (AMT ). On AMT -capable machines, the Wake on LAN feature
also supports the Force-Shutdown and Force-Restart actions in Studio and Director. Additionally, a Restart action is
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.195
available in StoreFront and Citrix Receiver. IMPORTANT: AMT support is available only when using ConfigMgr 2012 or
2012 R2, not ConfigMgr 2016.
Configure ConfigMgr to use the Wake on LAN feature. T hen, when you use Studio to create a Remote PC Access
deployment (or when you add another power management connection to be used for Remote PC Access), enable the
power management feature and specify ConfigMgr access information.
For configuration details, see Configuration Manager and Remote PC Access Wake on LAN.
Configuration Manager and Remote PC Access Wake on LAN
To configure the Remote PC Access Wake on LAN feature, complete the following before installing a VDA on the office
PCs.
Configure ConfigMgr 2012, 2012 R2, or 2016 within the organization. T hen deploy the ConfigMgr client to all Remote PC
Access machines, allowing time for the scheduled SCCM inventory cycle to run (or force one manually, if required). T he
access credentials you specify in Studio to configure the connection to ConfigMgr must include collections in the scope
and the Remote T ools Operator role.
For Intel Active Management T echnology (AMT ) support:
T he minimum supported version on the PC must be AMT 3.2.1.
Provision the PC for AMT use with certificates and associated provisioning processes.
Only ConfigMgr 2012 and 2012 R2 can be used, not ConfigMgr 2016.
For ConfigMgr Wake Proxy and/or magic packet support:
Configure Wake on LAN in each PC's BIOS settings.
For Wake Proxy support, enable the option in ConfigMgr. For each subnet in the organization that contains PCs that
will 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 ConfigMgr address and access
credentials, plus a name.
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 and specify the new power
management connection.
You can edit a power management connection to configure advanced settings. You can enable:
Wake-up proxy delivered by ConfigMgr.
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.
T he 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.
Citrix Cloud deployments: configuration sequence and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.196
considerations
See CT X220737: How to Enable XenDesktop Remote PC Access in Citrix Cloud.
On-premises deployments: configuration sequence
and considerations
Bef ore you create the Remote PC Access Site:
If you will use the Remote PC Access power management feature (also known as Remote PC Access Wake on LAN),
complete the configuration tasks on the PCs and on Microsoft System Center Configuration Manager (ConfigMgr) before
creating the Remote PC Access deployment in Studio. See Configuration Manager and Remote PC Access Wake on LAN for
details.
In the Site creation wizard:
Select the Remote PC Access Site type.
On the Power Management page, you can enable or disable power management for the machines in the default
Remote PC Access machine catalog. If you enable power management, specify ConfigMgr connection information.
On the Users and Machine Accounts pages, specify users and machine accounts.
Creating a Remote PC Access Site creates a default machine catalog named Remote PC Access Machines and a default
Delivery Group named Remote PC Access Desktops.
If you create another machine catalog f or use with Remote PC Access:
On the Operating System page, select Remote PC Access and choose a power management connection. You can also
choose not to use power management. If there are no configured power management connections, you can add one
after you finish the machine catalog creation wizard (connection type = Microsoft Configuration Manager Wake on
LAN), and then edit the catalog, specifying that new connection.
On the Machine Accounts page, you can select from the machine accounts or Organizational Units (OUs) displayed, or
add machine accounts and OUs.
Install the VDA on the of fice PCs used f or local and remote access. Typically, you deploy the VDA automatically using
your package management software; however, for proof-of-concept or small deployments, you can install the VDA
manually on each office PC. T here are several ways you can install a desktop VDA for a Remote PC Access deployment.
Use the full-product or VDAWorkstationSetup.exe installer
Graphic interface: Select Remote PC Access on the Environment page of the wizard. T he components on the
Additional Components page are not selected by default. T hey are not required for Remote PC Access operation.
Command-line interface: specify the /remotepc option. T his option prevents the installation of the following
components (which are equivalent to the items on the Additional Components page in the wizard):
App-V
Citrix User Profile Manager
Citrix User Profile Manager WMI Plugin
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.197
Machine Identity Service
Personal vDisk
Alternatively, you can use the /exclude option to exclude each of these components.
Use the VDAWorkstationCoreSetup.exe installer. Neither Citrix Receiver nor any additional components can be installed
with this installer.
After the VDA is installed, the next domain user that logs on to a console session (locally or through RDP) on the office PC
is automatically assigned to the Remote PC Access desktop. If additional domain users log on to a console session, they are
also added to the desktop user list, subject to any restrictions you have configured.
To use RDP connections outside of your XenApp or XenDesktop environment, you must add users or groups to the Direct
Access Users group.
Instruct users to download and install Citrix Receiver onto each client device they will use to access the of fice
PC remotely. Citrix Receiver is available from http://www.citrix.com or the application distribution systems for supported
mobile devices.
Troubleshooting
Diagnostic information about Remote PC Access is written to the Windows Application Event log. Informational 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
For on-premises deployments only: If power management for Remote PC Access is enabled, subnet-directed broadcasts
might fail to start machines that are located 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 management connection).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.198
App-V
Dec 18 , 20 17
Using App-V with XenApp and XenDesktop
Microsoft Application Virtualization (App-V) lets you deploy, update, and support applications as services. 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 connection to the internet.
T he following table lists supported versions.
App-V
5.0 and 5.0 SP1
XenDesktop and XenApp versions
Delivery Controller
VDA
XenDesktop 7 through current
7.0 through current
XenApp 7.5 through current
5.0 SP2
XenDesktop 7 through current
7.1 through current
XenApp 7.5 through current
5.0 SP3 and 5.1
XenDesktop 7.6 through current
7.6.300 through current
XenApp 7.6 through current
XenDesktop 7.12 through current
App-V in Windows Server 2016
XenApp 7.12 through current
7.12 through current
T he App-V client does not support offline access to applications. App-V integration support includes using SMB shares for
applications. T he HT T P protocol is not supported.
If you're not familiar with App-V, see the Microsoft documentation. Here's a recap of the App-V components mentioned in
this article:
Management server. Provides a centralized console to manage App-V infrastructure and delivers virtual applications to
both the App-V Desktop Client and a Remote Desktop Services Client. T he App-V management server authenticates,
requests, and provides the security, metering, monitoring, and data gathering required by the administrator. T he 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.199
Client. Retrieves virtual applications, publishes the applications on the client, and automatically sets up and manages
virtual environments at runtime on Windows devices. You install the App-V client on the VDA, where it stores userspecific 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:
T hrough Citrix Receiver
From the Start menu
T hrough the App-V client and Citrix Receiver
Simultaneously by multiple users on multiple devices
T hrough 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 communication between Studio and
the App-V servers for discovery, configuration, and downloading to the VDAs. T his incurs hardware, infrastructure, and
administration overhead. Studio and the App-V servers must remain synchronized, particularly for user permissions.
T his is called the dual admin management method because App-V package and application access requires both
Studio and the App-V server consoles. T his method works best in closely coupled App-V and Citrix deployments. In this
method, the management server handles the dynamic configuration files.
Network share: Packages and XML deployment configuration files placed on a network share removes Studio's
dependence on the App-V server and database infrastructure, thereby lowering overhead. (You still need to install the
Microsoft App-V client on each VDA.)
T his is called the single admin management method because App-V package and application use requires only 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. In this method, the Citrix App-V components process the Deployment Configuration Files
when the application is launched. (User Configuration Files are not supported.)
Application Library is a Citrix term for a caching repository that stores information about App-V packages. T he
Application Library also stores information about other Citrix application delivery technologies.
You can use one or both management methods simultaneously. In other words, when you add applications to Delivery
Groups, the applications can come from App-V packages located on App-V servers and/or on a network share.
Note
If you are using both management methods simultaneously, and the App-V package has a dynamic configuration file in both
locations, the file in the App-V server (dual management) is used.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.200
When you select Configuration > App-V Publishing in the Studio navigation pane, the display shows App-V package
names and sources. T he 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 package, can be used to
change its characteristics. For example, you can use them to define extra application 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. T hese 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 customizations to the package.
T hese files are expected to be named <packageFileName>_UserConfig.xml and located in the same folder as the App-V
package they apply to. Only supported by dual admin management.
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 dynamic 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. T he entire
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.
Isolation groups
When you use the App-V single admin method, creating isolation groups allow you to specify interdependent groups of
applications that must run in the sandbox. T his 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. T hose packages 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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.201
added that application to the same Delivery Group that contains the primary application.
T his 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). T hen, 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.
Setup
The following table summarizes the sequence of setup tasks for using App-V in XenApp and XenDesktop.
Management method
Task
Single admin
Dual admin
X
X
Deploy App-V
X
X
Packaging and placement
X
Configure App-V server addresses in Studio
X
Install software on VDA machines
X
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 Microsof t App-V
For App-V deployment instructions, see https://technet.microsoft.com/en-us/windows/hh826068.
Optionally, change App-V publishing server settings. Citrix recommends using the SDK cmdlets on the Controller. See the
SDK documentation for details.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.202
T o view publishing server settings, enter Get-CtxAppvServerSetting -AppVPublishingServer < pubServer>.
T o ensure that App-V applications launch properly, enter Set-CtxAppvServerSetting –UserRef reshonLogon 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. T his 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 configuration files, available on a
UNC or SMB shared network location. Ensure that the Studio administrator 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
HT T P 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 addresses 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. T hese properties are used on the VDAs to connect to App-V
publishing servers. If this happens, reconfigure the nondefault values for any reset properties on the servers.
T his 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 Conf iguration > App-V Publishing in the Studio navigation pane.
2. If you have not previously specified App-V server addresses, select Add Microsof t Server in the Actions pane.
3. T o change App-V server addresses, select Edit Microsof t 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.203
5. T est the connection to those servers before closing the dialog box. If the test fails, see the T roubleshoot section below.
Later, if you want to remove all links to the App-V management and publishing servers and stop Studio from discovering
App-V packages from those servers, select Remove Microsof t Server in the Actions pane. T his 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 sof tware on VDA machines
Machines containing VDAs must have two sets of software installed to support App-V: one from Microsoft and the other
from Citrix.
Microsof t App-V client
T his software retrieves virtual applications, publishes the applications on the client, and automatically sets up and
manages virtual environments at runtime on Windows devices. T he App-V client stores user-specific virtual application
settings, such as registry and file changes in each user's profile.
T he 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). T he Get-AppVStatus cmdlet retrieves the current enablement status.
T ip: After you install the App-V client, with Administrator permissions, run the PowerShell GetAppvClientConfiguration cmdlet, and ensure that EnablePackageScripts is set to 1. If it is not set to 1, run SetAppvClientConfiguration -EnablePackageScripts $true.
Citrix App-V components
T he Citrix App-V component software is installed and enabled by default when you install a VDA.
You can control this default action during VDA installation. In the graphical interface, clear the Citrix Personalization
f or App-V - VDA check box on the Additional Components page. In the command line interface, include the
/exclude "Citrix Personalization f or App-V - VDA" option.
If you expressly disable installation of the Citrix App-V components during VDA installation, but later want to use AppV 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
T hese 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
1. Select Conf iguration > App-V Publishing in the Studio navigation pane.
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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.204
Remove an App-V package f rom 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 applications can still be launched. T he
package remains in its physical network location. (T his effect differs from removing an App-V application from a Delivery
Group.)
1. Select Conf iguration > App-V Publishing in the Studio navigation pane.
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. T he selected applications should now appear in the Packages in Isolation Group list. In the Deployment dropdown next to each application, select either Explicit or Automatic. You can also use the up and down arrows to change
the order of applications 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 description, add or remove
applications, change their deployment type, or change the application order.
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
T he 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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.205
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:
1. Select Applications in the Studio navigation pane.
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 Application Library. T he
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. T hen 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.
Troubleshoot
Issues that can occur only when using the dual admin method are marked (DUAL).
(DUAL) T here 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? T he Studio administrator must belong to the
"administrators" group on the App-V management server so that they can communicate with it.
(DUAL) T he 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 http://technet.microsoft.com/enus/magazine/ff700227.aspx.
Is the Studio administrator also an App-V server administrator? T he Studio administrator must belong to the
"administrators" group on the App-V management server so that they can communicate with it.
Is file sharing enabled on the App-V server? Enter \\< App-V server FQDN> in Windows Explorer 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 Passwords, specifying the credentials of the user who has
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.206
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: "T he config setting TrustedHosts cannot
be changed because use is controlled by policies. T he 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? T he Studio administrator 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 Manager; each App-V server
should be in a Started and Running state.
Is PowerShell remoting enabled on both App-V servers? If not, see http://technet.microsoft.com/enus/magazine/ff700227.aspx.
Do packages have the appropriate security permissions for the Studio administrator to access?
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 T emp is pointing to the correct location, and that there is enough space available in the
T emp 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\SOFT WARE\Policies\Citrix\AppV. Ensure that the AppVServers key has the following value
format: AppVManagementServer+metadata;PublishingServer (for example: http://xmas-demoappv.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 PowerShell ExecutionPolicy is set
to RemoteSigned. T he 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 Computer
Configuration > Policies > Administrative T emplates > Windows Components > Windows PowerShell> T urn on Script
Execution.
If these steps do not resolve the issues, enable and examine the logs.
Logs
App-V configuration-related logs are located at C:\CtxAppvLogs. T he application launch logs are located at:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.207
%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:\ProgramFiles\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:\ProgramFiles\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.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.208
AppDisks
Nov 28 , 20 17
Overview
Managing applications and managing the images they are installed on can be a challenge. T he Citrix AppDisks feature is a
solution. AppDisks separate applications and groups of applications from the operating system, enabling you to manage
them independently.
You can create different AppDisks containing applications designed for individual user groups, and then assemble the
AppDisks on a master image of your choice. Grouping and managing applications this way gives you finer control of
applications, and reduces the number of master images you maintain. T his simplifies IT administration and enables you to be
more responsive to user needs. You deliver the applications in AppDisks through Delivery Groups.
If your deployment also includes Citrix AppDNA, you can integrate the AppDisks feature with it; AppDNA allows XenApp
and XenDesktop to perform automatic analysis of applications on a per-AppDisk basis. Using AppDNA helps make the most
of the AppDisks feature. Without it, application compatibility is not tested or reported.
AppDisks differ from other application-provisioning technologies in two ways: isolation and change management.
Microsoft App-V allows incompatible applications to exist together by isolating them. T he AppDisks feature does not
isolate applications. It separates applications (and supporting files and registry keys) from the OS. T o the OS and the
user, AppDisks look and behave as if they are installed directly on a master image.
Change management (updating master images and testing the compatibility of updates with installed applications) can
be a significant expense. AppDNA reports help identify issues and suggest remediation steps. For example, AppDNA can
identify applications that have common dependencies such as .NET , so you can install them on a single common base
image. AppDNA can also identify applications that load early in the OS startup sequence, so that you can then ensure
they behave as expected.
Good to know:
After updating an image, some applications may fail to work properly due to an ability to verify previously installed
licenses. For example, after an image upgrade, launching Microsoft Office may display an error message similar to:
"Microsoft Office Professional Plus 2010 cannot verify the license for this application. A repair attempt failed or was
canceled by the user, the
application will not shut down."
T o resolve this issue, uninstall Microsoft Office and install the new version on the base image.
In some cases, downloading Metro apps from the Windows Store to a published catalog's virtual machine fails after a
long time.
Citrix recommends that you always put all Microsoft Office components in the same AppDisk. For example, one AppDisk
with Microsoft Office with Project, and another AppDisk with Microsoft Office with Project and Visio.
On some systems, SCCM crashes when updating an image. T his scenario occurs when updates are made to the base
image, then applied, which results in failure of the SCCM client. T o resolve this issue, install the SCCM client instance in
the base image first.
In some cases, an application installed on the AppDisk may fail to appear in the Windows Start menu after it is assigned
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.209
to a Delivery Group and assigned a user's virtual machine. See How applications appear in the Start Menu for more
information.
Users are unaware of the separation of applications and the OS, or any other aspect of the AppDisks feature.
Applications behave as if they are installed on the image. AppDisks containing complex applications may result in a slight
delay in desktop startup.
You may only use AppDisks with Hosted Shared and Pooled desktops.
You can use AppDisks with hosted shared desktops.
You may be able to share AppDisks across master images and OS platforms (on a per-application basis); however, this will
not work for all applications. If you have applications with an install script for a desktop OS that prevents them from
working on a server OS, Citrix recommends packaging the applications separately for the two OSs.
In many cases, AppDisks work on different OSs. For example, you can add an AppDisk that was created on a Windows 7
VM to a Delivery Group containing Windows 2008 R2 machines, as long as both OSs have the same bitness (32 bit or 64
bit) and both support the application. However, Citrix recommends you do not add an AppDisk created on a later OS
version (such as Windows 10) to a Delivery Group containing machines running an earlier OS version (such as Windows 7),
because it might not work correctly.
If you need to provide access to an AppDisk's applications to only a subset of users in a Delivery Group, Citrix
recommends using Group Policy to hide an application in an AppDisk from some users. T hat application's executable file
remains available, but will not run for those users.
In Russian and Chinese environments running the Windows 7 OS, the reboot dialog fails to disappear automatically; in
such cases, after logging on to a delivered desktop the reboot dialog appears and should disappear quickly.
When using the Upload-PvDDiags script tool, log information related to the PVD user layer is missing when the user's
drive designation is not set to 'P'.
In environments set to display Basque language, a Windows 7 OS may fail to properly display the appropriate language
on the reboot prompt screen. When you set the language to Basque, make sure that you have already installed French
or Spanish as the parent language, then install Basque and set it as the current language.
When shutting down a computer, the PVD update reminder pops up even if the PVD disk is set to read-only mode.
During an in-place upgrade, a registry file (DaFsFilter) could be deleted, which causes the upgrade to fail.
Tip
When creating an AppDisk, use a VM with only the OS installed (that is, do not include other apps); the OS should contain all updates
prior to creating the AppDisk.
Deployment overview
T he following list summarizes the steps to deploy AppDisks. Details are provided later in this article.
1. From your hypervisor management console, install a Virtual Delivery Agent (VDA) on a VM.
2. Create an AppDisk, which includes completing steps from your hypervisor management console and in Studio.
3. From your hypervisor management console, install applications on the AppDisk.
4. Seal the AppDisk (from the hypervisor management console or in Studio). Sealing allows XenApp and XenDesktop to
record the AppDisk's applications and supporting files in an Application Library (AppLibrary).
5. In Studio, create or edit a Delivery Group and select the AppDisks to include; this is called assigning the AppDisks (even
though you use the Manage AppDisks action in Studio). When VMs in the Delivery Group start up, XenApp and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.210
XenDesktop coordinate with the AppLibrary, then interact with Creation Services (MCS) or Provisioning Services (PVS),
and the Delivery Controller to stream the boot devices after AppDisks are configured on them.
Requirements
Using AppDisks has requirements in addition to those listed in the System requirements article.
T he AppDisks feature is supported only in deployments containing (at minimum) versions of the Delivery Controller and
Studio provided in the XenApp and XenDesktop 7.8 download, including the prerequisites that the installer automatically
deploys (such as .NET 4.5.2).
AppDisks can be created on the same Windows OS versions that are supported for VDAs. T he machines selected for
Delivery Groups that will use AppDisks must have at least VDA version 7.8 installed.
Citrix recommends that you install or upgrade all machines with the most recent VDA version (and then upgrade
Machine Catalogs and Delivery Groups, if needed). When creating a Delivery Group, if you select machines that have
different VDA versions installed, the Delivery Group will be compatible with the earliest VDA version. (T his is called the
group's functional level.) For more information about functional level, see the Create Delivery Groups article.
To provision VMs that will be used to create AppDisks, you can use:
MCS provided with the 7.8 Controller (minimum).
PVS version provided on the download page with your XenApp and XenDesktop version.
Supported hypervisors:
XenServer
VMware (minimum version 5.1)
Microsoft System Center Virtual Machine Manager
AppDisks cannot be used with other host hypervisors and cloud service types supported for XenApp and XenDesktop.
Creating AppDisks is not supported with machines in MCS catalogs that use caching of temporary data.
Note
You can attach AppDisks to MCS-provisioned machines using write caching, but they cannot be used to create AppDisks.
Remote PC Access catalogs do not support AppDisks.
T he Windows Volume Shadow Service must be enabled on the VM where you are creating an AppDisk. T his service is
enabled by default.
Delivery Groups used with AppDisks can contain machines from pooled random Machine Catalogs containing server OS or
desktop OS machines. You cannot use AppDisks with machines from other catalog types, such as pooled static or
dedicated (assigned).
Machines on which Studio is installed must have .NET Framework 3.5 installed (in addition to any other installed .NET
versions).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.211
AppDisks can affect storage. For details, see Storage and performance considerations.
If you use AppDNA:
Review the AppDNA documentation and the AppDisk FAQ.
T he AppDNA software must be installed on a different server from a Controller. Use the AppDNA version supplied with
this XenApp and XenDesktop release. For other AppDNA requirements, see its documentation.
On the AppDNA server, make sure there is a firewall exception for the default port 8199.
Do not disable an AppDNA connection while creating an AppDisk.
When you create the XenApp or XenDesktop Site, you can enable compatibility analysis with AppDNA on the Additional
Features page of the Site creation wizard. You can also enable/disable it later by selecting Conf iguration > AppDNA in
the Studio navigation pane.
Clicking on the View Issue Report link in Studio displays the AppDNA report, however the OS combinations that AppDNA
uses by default are Window 7 64-bit for desktop delivery groups and Windows Server 2012 R2 for server delivery groups.
If your delivery groups contain different versions of Windows, the default image combinations in the reports that Studio
shows will be incorrect. T o work around this issue, manually edit the solution in AppDNA after Studio has created it.
T here is a dependency between Studio and AppDNA server versions.
From version 7.12, Studio must be the same, or a higher version than the AppDNA server.
For versions 7.9 and 7.11, Studio and AppDNA server versions must match.
T he following table summarizes which versions work together (Yes = versions work together, - = versions don't work
together):
Product Version
Studio 7.9
Studio 7.11
Studio 7.12
Studio 7.13
Studio 7.14
Studio 7.15
AppDNA 7.9
Yes
-
-
-
-
-
AppDNA 7.11
-
Yes
-
-
-
-
AppDNA 7.12
-
-
Yes
Yes
Yes
Yes
AppDNA 7.13
-
-
Yes
Yes
Yes
Yes
AppDNA 7.14
-
-
-
-
Yes
Yes
AppDNA 7.15
-
-
-
-
-
Yes
Storage and perf ormance considerations
Separating applications and the OS using two disks, and storing those disks in different areas can affect your storage
strategy. T he following graphic illustrates the MCS and PVS storage architectures. "WC" indicates the write cache, and
"T hin" indicates the thin disk used to store differences between a VM's AppDisk and OS virtual disks.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.212
In MCS environments:
You can continue to balance the size of the AppDisks and OS virtual disks (vDisks) using your organization's existing
sizing guidelines. If AppDisks are shared between multiple Delivery Groups, the overall storage capacity can be reduced.
OS vDisks and AppDisks are located in the same storage areas, so plan your storage capacity requirements carefully
to avoid any negative effect on capacity when you deploy AppDisks. AppDisks incur overhead, so be sure your storage
accommodates that overhead and the applications.
T here is no net effect on IOPS because the OS vDisks and AppDisks are located in the same storage area. T here are
no write cache considerations when using MCS.
In PVS environments:
You must allow for the increased capacity and IOPS as applications move from AppDisk storage to the hypervisorattached storage.
With PVS, OS vDisks and AppDisks use different storage areas. T he OS vDisk storage capacity is reduced, but the
hypervisor-attached storage is increased. So, you should size your PVS environments to accommodate those
changes.
AppDisks in the hypervisor-attached storage require more IOPS while the OS vDisks require fewer.
Write cache: PVS uses a dynamic VHDX file on an NT FS formatted drive; when blocks are written to the write cache,
the VHDX file is dynamically extended. When AppDisks are attached to their associated VM, they are merged with
the OS vDisks to provide a unified view of the file system. T his merging typically results in additional data being written
to the write caches, which increases the size of the write cache file. You should account for this in your capacity
planning.
In either MCS or PVS environments, remember to decrease the size of the OS vDisk to take advantage of the AppDisks you
create. If you don’t, plan to use more storage.
When many users in a Site turn on their computers simultaneously (for example, at the beginning of the workday), the
multiple startup requests apply pressure on the hypervisor, which can affect performance. For PVS, applications are not
located on the OS vDisk, so fewer requests are made to the PVS server. With the resulting lighter load on each target
device, the PVS server can stream to more targets. However, be aware that the increased target-server density might
negatively affect boot storm performance.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.213
Create an AppDisk
T here are two ways to create an AppDisk, install applications on it, and then seal it. Both methods include steps you
complete from your hypervisor management console and in Studio. T he methods differ in where you complete most the
steps.
Regardless of which method you use:
Allow 30 minutes for AppDisk creation portion.
If you use AppDNA, following the guidance in the Requirements section above. Do not disable an AppDNA connection
while creating an AppDisk.
When you add applications to an AppDisk, be sure to install applications for all users. Re-arm any applications that use
Key Management Server (KMS) activation. For details, see the application’s documentation.
Files, folders, and registry entries created in user-specific locations during AppDisk creation are not retained. Also, some
applications run a first-time-use wizard to create user data during installation. Use a profile management solution to
retain this data and prevent the wizard from appearing each time the AppDisk starts.
If you are using AppDNA, analysis starts automatically after the creation process completes. During this interval, the
AppDisk's status in Studio is "Analyzing."
PVS considerations
AppDisks on machines from Machine Catalogs created by Provisioning Services require additional configuration during
AppDisk creation. From the Provisioning Services console:
1. Create a new version of the vDisk associated with the device collection that contains the VM.
2. Place the VM into maintenance mode.
3. During AppDisk creation, select the maintenance version on the boot screen every time the VM restarts.
4. After you seal the AppDisk, place the VM back into production, and delete the vDisk version you created.
Create an AppDisk primarily in Studio
T his procedure includes three tasks: create the AppDisk, create applications on the AppDisk, and then seal the AppDisk.
Create an AppDisk:
1. Select AppDisks in the Studio navigation pane and then select Create AppDisk in the Actions pane.
2. Review the information on the Introduction page of the wizard and then click Next.
3. On the Create AppDisk page, select the Create new AppDisk radio button. Select either a predefined disk size (small,
medium, or large) or specify a disk size in GB; the minimum size is 3 GB. T he disk size should be large enough to hold the
applications you will add. Click Next.
4. On the Preparation Machine page, select a random pooled catalog to be used as the master image on which the
AppDisk will be built. Note: T he display lists all the Machine Catalogs in the Site, separated by type; only those catalogs
that contain at least one available machine can be selected. If you choose a catalog that does not contain random
pooled VMs, the AppDisk creation will fail. After you select a VM from a random pooled catalog, click Next.
5. On the Summary page, type a name and description for the AppDisk. Review the information you specified on previous
wizard pages. Click Finish.
Remember: If you are using PVS, follow the guidance in the PVS considerations section above.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.214
After the wizard closes, the Studio display for the new AppDisk indicates "Creating." After the AppDisk is created, the
display changes to "Ready to install applications."
Install applications on the AppDisk:
From your hypervisor management console, install applications on the AppDisk. (Tip: If you forget the VM name, select
AppDisks in the Studio navigation pane and then select Install Applications in the Actions pane to display its name.) See
the hypervisor documentation for information about installing applications. (Remember: You must install applications on
the AppDisk from your hypervisor management console. Do not use the Install Applications task in the Studio Actions
pane.)
Seal the AppDisk:
1. Select AppDisks in the Studio navigation pane.
2. Select the AppDisk you created, and then select Seal AppDisk in the Actions pane.
After you create the AppDisk, install applications on it, and then seal it, assign it to a Delivery Group.
Canceling AppDisk preparation and sealing
In some cases, an administrator may need to cancel AppDisk creation or sealing:
1. Access the VM.
2. Close the dialog:
3. After closing the dialog, a popup message appears requesting verification to cancel the selected operation; click Yes.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.215
Note
If you cancel AppDisk preparation, rebooting the machine returns it to the initial state, otherwise you need to create a clean VM.
Create an AppDisk on the hypervisor and import it to Studio
In this procedure, you complete the AppDisk creation and preparation tasks from the hypervisor management console and then import AppDisk into Studio.
Prepare, install applications, and seal an AppDisk on the hypervisor:
1. From the hypervisor management console, create a VM and install a VDA.
2. Power off the machine and take a snapshot of it.
3. Create a new machine from the snapshot and then add a new disk to it. T his disk (which will become the AppDisk) must
be large enough to hold all the applications you will install on it.
4. Start the machine and select Start > Prepare AppDisk. If this Start menu shortcut is not available on the hypervisor,
open a command prompt at C:\Program Files\Citrix\personal vDisk\bin and type: CtxPvD.Exe –s LayerCreationBegin.
T he machine restarts and prepares the disk. A second restart occurs after several minutes when the preparation
completes.
5. Install the applications you want to make available to users.
6. Double-click the Package AppDisk shortcut on the machine’s desktop. T he machine restarts again and the sealing
process starts. When the "in process" dialog closes, power off the VM.
Use Studio to import the AppDisk you created on the hypervisor:
1. Select AppDisks in the Studio navigation pane and then select Create AppDisk in the Actions pane.
2. On the Introduction page, review the information and then click Next.
3. On the Create AppDisk page, select the Import existing AppDisk radio button. Select the resource (network and
storage) where the AppDisk you created resides on the hypervisor. Click Next.
4. On the Preparation Machine page, browse to the machine, select the disk, and then click Next.
5. On the Summary page, type a name and description for the AppDisk. Review the information you specified on previous
wizard pages. Click Finish. Studio imports the AppDisk.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.216
After you import the AppDisk into Studio, assign it to a Delivery Group.
Assign an AppDisk to a Delivery Group
You can assign one or more AppDisks to a Delivery Group when you create the Delivery Group or later. T he AppDisks
information you provide is essentially the same.
If you are adding AppDisks to a Delivery Group that you are creating, use the following guidance for the AppDisks page in
the Create Delivery Group wizard. (For information about other pages in that wizard, see the Create Delivery Groups article.)
To add (or remove) AppDisks in an existing Delivery Group:
1. Select Delivery Groups in the Studio navigation pane.
2. Select a Delivery Group and then select Manage AppDisks in the Actions pane. See the following guidance for the
AppDisks page.
3. When you change the AppDisk configuration in a Delivery Group, a restart of the machines in the group is required. On
the Rollout Strategy page, follow the guidance in Create a restart schedule.
AppDisks page:
T he AppDisks page (in the Create Delivery Group wizard or in the Manage AppDisks flow) lists the AppDisks already
deployed for the Delivery Group and their priority. (If you are creating the Delivery Group, the list will be empty.) For more
information, see the AppDisk priority section.
1. Click Add. T he Select AppDisks dialog box lists all AppDisks in the left column. AppDisks that are already assigned to this
Delivery Group have enabled checkboxes and cannot be selected.
2. Select one or more checkboxes for available AppDisks in the left column. T he right column lists the applications on the
AppDisk. (Selecting the Applications tab above the right column lists applications in a format similar to a Start menu;
selecting the Installed packages tab lists applications in a format similar to the Programs and Features list.)
3. After selecting one or more available AppDisks, click OK.
4. Click Next on the AppDisks page.
AppDisk priority in a Delivery Group
When a Delivery Group has more than one AppDisk assigned, the AppDisks page (in the Create Delivery Group, Edit Delivery
Group, and Manage AppDisks displays) lists the AppDisks in descending priority. Entries at the top of the list have the higher
priority. Priority indicates the order in which the AppDisks are processed.
You can use the up and down arrows adjacent to the list to change the AppDisk priority. If AppDNA is integrated with your
AppDisk deployment, it automatically analyzes the applications and then sets the priority when the AppDisks are assigned
to the Delivery Group. Later, if you add or remove AppDisks from the group, clicking Auto-Order instructs AppDNA to reanalyze the current list of AppDisks and then determine the priorities. T he analysis (and priority reordering, if needed) may
take several moments to complete.
Managing AppDisks
After you create and assign AppDisks to Delivery Groups, you can change the AppDisk's properties through the AppDisks
node in the Studio navigation pane. Changes to applications in an AppDisk must be done from the hypervisor management
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.217
console.
Important
You can use the Windows Update service to update applications (such as the Office suite) on an AppDisk. However, do not use the
Windows Update Service to apply operating system updates to an AppDisk. Apply operating system updates to the master image,
not the AppDisk; otherwise, the AppDisk will not initialize correctly.
When applying patches and other updates to applications in an AppDisk, apply only those that the application requires. Do not
apply updates for other applications.
When installing Windows updates, first deselect all entries and then select the subset required by the applications on the
AppDisks you're updating.
Antivirus considerations for AppDisk creation
In some cases, you may run into problems trying to create an AppDisk due to scenarios where the base VM has an antivirus
(A/V) agent installed. In such cases, AppDisk creation may fail when certain processes are flagged by the A/V agent. T hese
processes, CtxPvD.exe and CtxPvDSrv.exe must be added to the exception list for the A/V agent used by the base VM.
T his section provides information about adding exceptions for the following antivirus applications:
Windows Defender (for Windows 10)
OfficeScan (version 11.0)
Symantec (version 12.1.16)
McAfee (version 4.8)
Windows Def ender
If your base VM uses Windows Defender (version 10):
1. Log into your computer with local administrator privileges.
2. Select the Windows Defender icon and right click to display the Open button:
3. In the Windows Defender console, select Settings in the upper right portion of the interface:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.218
4. In the Exclusions portion of the Settings screen, click Add an exclusion:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.219
5. In the Add an exclusion screen, select Exclude a .exe, .com, or .scr process:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.220
6. In the Add exclusion screen, enter the name of the exclusion; both CtxPvD.exe and CtxPvDSvc.exe must be added to
prevent conflicts when creating an AppDisk. After entering the exclusion name, click OK:
After adding the exclusions, they appear in the list of excluded processes in the Settings screen:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.221
Of ficeScan
If your base VM uses OfficeScan (version 11):
1. Launch the OfficeScan console.
2. Click the lock icon in the lower left portion of the interface, and enter your password:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.222
3. Click the Settings icon to display configuration options.
4. In the Settings screen, select the Protection tab.
5. In the Protection tab, scroll down until you locate the Exclusions section.
6. In the Files section, click Add, and enter the following AppDisk processes to the exception list:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.223
command
COPY
C:\Program Files\Citrix\personal vDisk\bin\CtxPvD.exe
C:\Program Files\Citrix\personal vDisk\bin\CtxPvDSvc.exe
7. Click Apply, then OK to add the exclusions.
Symantec
If your base VM uses Symantec (version 12.1.16):
1. Launch the Symantec console.
2. Click Change Settings.
3. In the Exceptions section, click Conf igure Settings:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.224
4. In the Configure Settings screen, click Add.
5. After clicking Add, a context menu appears to allow you to specify the application type. Select Application Exception:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.225
6. In the Exceptions screen, enter the following AppDisk file paths and set the action to Ignore:
command
COPY
C:\Program Files\Citrix\personal vDisk\bin\CtxPvD.exe
C:\Program Files\Citrix\personal vDisk\bin\CtxPvDSvc.exe
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.226
T he noted exceptions are added to the list. Close the window to apply your changes:
McAf ee
If your base VM uses McAfee (verson 4.8):
1. Right click the McAfee icon, and expand the Quick Settings option.
2. In the expanded menu, select On-Access Scan Properties:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.227
3. In the On-Access Scan Properties screen, click All Processes:
4. Select the Exclusions tab.
5. Click the Exclusions button.
6. In the Set Exclusions screen, click Add:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.228
7. In the Add Exclusion Item screen, select By name/location (can include wildcards * or ?). Click Browse to locate the
exclusion executables:
command
COPY
C:\Program Files\Citrix\personal vDisk\bin\CtxPvD.exe
C:\Program Files\Citrix\personal vDisk\bin\CtxPvDSvc.exe
8. Click OK.
9. T he Set Exclusions screen now displays the added exclusions. Click OK to apply the changes:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.229
Note
After configuring these exclusions, create the AppDisk.
How applications appear in the Start menu
If a new AppDisk is created and an app is made available for all users the disk is attached to the desktop and a shortcut
appears for the app in the Start menu. When an AppDisk is created and installed for the current user only and the disk is
attached to the desktop, the shortcut for the app fails to appear in the Start menu.
For example, create a new app and make it available for all users:
1. Install an app on the AppDisk (for example, Beyond Compare is the selected app):
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.230
2. Attach the disk to the desktop; the shortcut for the newly installed app (Beyond Compare) appears in the Start menu:
To install an app for the current user only:
1. Install an app on the AppDisk and make it available for the current user:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.231
2. Attach the disk to the desktop; note that the shortcut does not appear in the Start menu:
AppDisk logging updates
T his release provides an enhancement to the AppDisk logging and support paradigm. With this update, AppDisk users can
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.232
now obtain diagnostic information and optionally upload it to the Citrix Insight Services (CIS) website.
How does it work?
T his new functionality uses a script-based PowerShell tool which identifies all of the log files created by AppDisk/PVD,
collects output from PowerShell commands containing information about the system (and processes), compresses
everything into a single organized file, and finally provides the option to either save the compressed folder locally, or upload
it to CIS (Citrix Insight Services).
Note
CIS gathers anonymous diagnostic information that it uses to improve AppDisk/PVD functionality. Access the Citrix CIS website to
manually upload the diagnostic bundle. You must login with your Citrix credentials to access this site.
Using PowerShell scripts to collect AppDisk/PVD log files
T he AppDisk/PVD installer adds two new scripts for diagnostic data collection:
Upload-AppDDiags.ps1 – performs AppDisk diagnostic data collection
Upload-PvDDiags.ps1 – performs PvD diagnostic data collection
Note
T hese scripts are added in C:\Program Files\Citrix\personal vDisk\bin\scripts. You must execute these PowerShell scripts as an
administrator.
Upload-AppDDiags.ps1
Use this script to initiate AppDisk diagnostic data collection and optionally manually upload the data to the CIS website.
command
https://docs.citrix.com
COPY
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.233
SYNTAX
Upload-AppDDiags [[-OutputFile] <string>] [-help] [<CommonParameters>]
-OutputFile
Local path for zip file instead of uploading to CIS
EXAMPLES
Upload-AppDDiags
Upload diagnostic data to Citrix CIS website using credentials entered by interactive user.
Upload-AppDDiags -OutputFile C:\MyDiags.zip
Save AppDisk diagnostic data to the specified zip file. You can access https://cis.citrix.com/ to upload it later.
Tip
When there is no –OutputFile argument, upload occurs. If –OutputFile is specified, the script creates a zip file that the you can
upload manually at a later time.
Upload-PvDDiags.ps1
Use this script to initiate PvD diagnostic data collection and optionally manually upload the data to the CIS website.
command
https://docs.citrix.com
COPY
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.234
SYNTAX
Upload-PvDDiags [[-OutputFile] <string>] [-help] [<CommonParameters>]
-OutputFile
Local path for zip file instead of uploading to CIS
EXAMPLES
Upload-PvDDiags
Upload PvD diagnostic data to Citrix CIS website using credentials entered by interactive user.
Upload-PvDDiags -OutputFile C:\MyDiags.zip
Save PvD diagnostic data to the specified zip file. You can access https://cis.citrix.com/ to upload it later.
Tip
When there is no –OutputFile argument, upload occurs. If –OutputFile is specified, the script creates a zip file that the you can
upload manually at a later time.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.235
XenApp Secure Browser
Nov 28 , 20 17
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 application, 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 XenApp 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 only compatible with Microsoft Internet Explorer. XenApp Secure Browser will display the
Internet Explorer compatible application as a tab within the Firefox browser.
Deploying XenApp Secure Browser Edition
Citrix recommends that you leverage the Citrix Smart Tools blueprint for the XenApp Secure Browser to simplify the
deployment.
T he XenApp Secure Browser blueprint includes scripts to automate the following tasks:
Install XenApp, including the Citrix License Server and StoreFront
Create a XenApp delivery site
Join the provisioned machines to your existing domain
Using the Citrix Smart Tools blueprint
To use the Citrix Smart Tools blueprint:
1. From the Citrix Cloud home page, navigate to Services; click Request T rial for Citrix Smart T ools. Once you request the
trial, you’ll receive an email notifying you when the trial service is available. T his generally takes 5-10 minutes.
2. Click Manage in the email you received when you requested the trail to display the Citrix Smart T ools home page.
3. Download the Citrix XenApp Secure Browser Edition ISO from the Citrix download site.
Consider the following after downloading the Secure Browser Edition ISO:
Start using the XenApp Secure Browser blueprint by following the instructions specified in XenApp Secure Installation
with a Citrix Smart T ools blueprint.
After completing the installation, further optimize your environment for webapp delivery by using the configuration
steps specified in the XenApp Secure Browser Deployment Guide.
Manually installing XenApp Secure Browser
To manually install XenApp Secure Browser version:
1. Download the Citrix XenApp Secure Browser Edition ISO from the Citrix download site.
2. Follow the install instructions for various components of XenApp.
3. Configure the edition and license mode for the Secure Browser edition after installation, by performing the following
additional steps:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.236
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 > Windows PowerShell.
Note: On 64-bit systems, this starts the 64-bit version. Both the 32-bit or 64-bit versions are supported.
b. Type Asnp Citrix* and press Enter to load the Citrix-specific PowerShell modules.
Note: "Asnp" represents Add-PSSnapin.
c. Check the current site settings and license mode, by running the Get-ConfigSite cmdlet.
d. Set the license mode to XenApp Secure Browser edition by running the Set-ConfigSite -ProductCode XDT ProductEdition BAS.
e. Confirm that the XenApp Secure Browser edition and license mode is set properly by running the GetBrokerSite cmdlet.
Note
After completing the installation, further optimize your environment for webapp delivery by using the configuration steps specified
in the XenApp Secure Browser Deployment Guide.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.237
Publish content
Nov 28 , 20 17
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. T his feature is known as published content. T he ability to publish content adds flexibility to how you deliver content to
users. You benefit from the existing access control and management of applications. And, you can specify what to use to
open the content: local or published applications.
T he published content appears just like other applications in StoreFront and Citrix Receiver. 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 T ype Association has been defined, a published application launches to open the resource.
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.)
New-BrokerApplicat ion – Applicat ionT ype P ublishedCont ent
-CommandLineExecut able < locat ion > -Name < app-name >
-Deskt opGroup < delivery-group-name >
T he ApplicationType property must be PublishedContent.
T he CommandLineExecutable property specifies the location of the published content. T he following formats are
supported, with a limit of 255 characters.
HT ML 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 FT P server (for example, ftp://ftp.citrix.com/code)
Document file on an FT P 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 XenApp and XenDesktop Service deployments, download and install the XenApp and XenDesktop Remote
PowerShell SDK.
For on-premises XenApp and XenDesktop deployments, use the PowerShell SDK that is installed with the Delivery
Controller. Adding a published content application requires a minimum version 7.11 Delivery Controller.
T he following procedures use examples. In the examples:
A machine catalog has been created.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.238
A Delivery Group named PublishedContentApps has been created. T he group uses a Server OS machine from the catalog.
T he 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.
T he 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 XenApp and XenDesktop 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.
$citrixUrl = "https://www.citrix.com/"
$appName = "Citrix Home Page"
New-BrokerApplication – ApplicationType PublishedContent
– CommandLineExecutable $citrixURL – Name $appName
– DesktopGroup $dg.Uid
Verify success:
Open StoreFront and log on as a user who can access applications in the PublishedContentApps Delivery Group. T he
display includes the newly created application with the default icon. T o 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. T he URL launches in a new tab in a locally running instance of your default
browser.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.239
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 RT F and a DOCX file in that share as a resource.
$rtfUNC = "\\GMSXJ-EDGE0.xd.local\PublishedResources\PublishedRT F.rtf "
$rtfAppName = "PublishedRT F"
New-BrokerApplication – ApplicationType PublishedContent
– CommandLineExecutable $rtfUNC -Name $rtfAppName
-DesktopGroup $dg.Uid
$docxUNC = "\\GMSXJ-EDGE0.xd.local\PublishedResources\PublishedDOCX.docx"
$docxAppName = "PublishedDOCX"
New-BrokerApplication – ApplicationType PublishedContent
– CommandLineExecutable $docxUNC -Name $docxAppName
-DesktopGroup $dg.Uid
Verify success:
Refresh your StoreFront window to see the newly published documents.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.240
Click the PublishedRT F and PublishedDOCX applications. Each document opens in a locally running WordPad.
View and edit PublishedContent applications
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.241
You manage published content using the same methods that you use for other application types. T he 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 Locat ion 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 application), 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.
Import ant : Turn on maintenance mode for the Delivery Group before editing the File Type Association. Remember to turn
off maintenance mode when you're done.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.242
Refresh StoreFront to load the File Type Association changes, and then click the PublishedRT F and PublishedDOCX
applications. Notice the difference. PublishedDOCX still opens in the local WordPad. However, PublishedRT F now opens in
the published WordPad due to the file type association.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.243
For more information
Create machine catalogs
Create Delivery Groups
Change application properties
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.244
Server VDI
Nov 28 , 20 17
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).
You can use the Enhanced Desktop Experience Citrix policy setting to make the server operating system look like a desktop
operating system.
T he following features cannot be used with Server VDI:
Personal vDisks
Hosted applications
Local App Access
Direct (non-brokered) desktop connections
Remote PC Access
For Server VDI to work with T WAIN devices such as scanners, the Windows Server Desktop Experience feature must be
installed.
Server VDI is currently supported on Windows Server 2016.
To install server VDI:
St ep 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. (T he VDA installation fails if these role services are installed.)
Ensure that the ‘Restrict each user to a single session’ property is enabled.
On Windows Server Windows Server 2016, edit the registry to set the Terminal Server setting. In registry key
HKEY_LOCAL_MACHINE\SYST EM\CurrentControlSet\Control\TerminalServer to set
DWORD fSingleSessionPerUser to 1.
St ep 2. Use the command line interface of the installer 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 Desktop OS
VDA on a server operating system. Using the command line overrides this behavior.)
On-premises XenApp and XenDesktop deployments: XenDesktopVdaSetup.exe /quiet /servervdi
On-premises XenApp and XenDesktop or XenDesktop Service deployments: VDAWorkstationSetup.exe /quiet
/servervdi
You can specify the Delivery Controller or Cloud Connector with the /controllers option.
Use the /enable_hdx_ports option to open ports in the firewall, unless the firewall is to be configured manually.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.245
Add the /masterimage option if you are installing the VDA on an image, and will use MCS to create server VMs from that
image.
Do not include options for features that are not supported with Server VDI, such as /baseimage.
St ep 3. Create a machine catalog for Server VDI.
On the Operat ing Syst em page, select Desktop OS.
On the Summary page, specify a machine catalog name and description for administrators that clearly identifies it as
Server VDI; this will be the only indicator in Studio that the catalog supports Server VDI.
When using Search in Studio, the Server VDI catalog you created is displayed on the Desktop OS Machines tab, even
though the VDA was installed on a server.
St ep 4 . Create a Delivery Group and assign the Server VDI catalog you created in the previous step.
If you did not specify the Delivery Controllers or Cloud Connector while installing the VDA, specify them afterward using the
Citrix policy setting, Active Directory, or by editing the VDA machine's registry values. See VDA registration.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.246
Personal vDisk
Nov 28 , 20 17
T he personal vDisk feature retains the single image management of pooled and streamed desktops while allowing users to
install applications and change their desktop settings. Unlike traditional Virtual Desktop Infrastructure (VDI) deployments
involving pooled desktops, where users lose their customization and personal applications when the administrator changes
the master image, deployments using personal vDisks retain those changes. T his means administrators can easily and
centrally manage their master images while providing users with a customized and personalized desktop experience.
Personal vDisks provide this separation by redirecting all changes made on the user's VM to a separate disk (the personal
vDisk), which is attached to the user's VM. T he content of the personal vDisk is blended at runtime with the content from
the master image to provide a unified experience. In this way, users can still access applications provisioned by their
administrator in the master image.
Personal vDisks have two parts, which use different drive letters and are by default equally sized:
User profile - T his contains user data, documents, and the user profile. By default this uses drive P: but you can choose a
different drive letter when you create a catalog with machines using personal vDisks. T he drive used also depends on the
EnableUserProfileRedirection setting.
Virtual Hard Disk (.vhd) file - T his contains all other items, for example applications installed in C:\Program Files. T his part is
not displayed in Windows Explorer and, since Version 5.6.7, does not require a drive letter.
Personal vDisks support the provisioning of department-level applications, as well as applications downloaded and installed
by users, including those that require drivers (except phase 1 drivers), databases, and machine management software. If a
user's change conflicts with an administrator's change, the personal vDisk provides a simple and automatic way to reconcile
the changes.
In addition, locally administered applications (such as those provisioned and managed by local IT departments) can also be
provisioned into the user's environment. T he user experiences no difference in usability; personal vDisks ensure all changes
made and all applications installed are stored on the vDisk. Where an application on a personal vDisk exactly matches one
on a master image, the copy on the personal vDisk is discarded to save space without the user losing access to the
application.
Physically, you store personal vDisks on the hypervisor but they do not have to be in the same location as other disks
attached to the virtual desktop. T his can lower the cost of personal vDisk storage.
During Site creation, when you create a connection, you define storage locations for disks that are used by VMs. You can
separate the Personal vDisks from the disks used by the operating system. Each VM must have access to a storage location
for both disks. If you use local storage for both, they must be accessible from the same hypervisor. To ensure this
requirement is met, Studio offers only compatible storage locations. Later, you can also add personal vDisks and storage for
them to existing hosts (but not machine catalogs) from Configuration > Hosting in Studio.
Back up personal vDisks regularly using any preferred method. T he vDisks are standard volumes in a hypervisor's storage tier,
so you can back them up, just like any other volume.
T he following improvements are included in this release:
T his version of personal vDisk contains performance improvements that reduce the amount of time it takes to apply an
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.247
image update to a personal vDisk catalog.
T he following known issues are fixed in this release:
Attempting an in-place upgrade of a base virtual machine from Microsoft Office 2010 to Microsoft Office 2013 resulted
in the user seeing a reconfiguration window followed by an error message; "Error 25004. T he product key you entered
cannot be used on this machine." In the past, it was recommended that Office 2010 be uninstalled in the base virtual
machine before installing Office 2013. Now, it is no longer necessary to uninstall Office 2010 when performing an inplace upgrade to the base virtual machine (#391225).
During the image update process, if a higher version of Microsoft .NET exists on the user's personal vDisk, it was
overwritten by a lower version from the base image. T his caused issues for users running certain applications installed on
personal vDisk which required the higher version, such as Visual Studio (#439009).
A Provisioning Services imaged disk with personal vDisk installed and enabled, cannot be used to create a non-personal
vdisk machine catalog. T his restriction has been removed (#485189).
New in version 7.6:
Improved personal vDisk error handling and reporting. In Studio, when you display PvD-enabled machines in a catalog, a
"PvD" tab provides monitoring status during image updates, plus estimated completion time and progress. Enhanced
state displays are also provided.
A personal vDisk Image Update Monitoring T ool for earlier releases is available from the ISO media
(ISO\Support\T ools\Scripts\PvdT ool). Monitoring capabilities are supported for previous releases, however the reporting
capabilities will not be as robust compared to the current release.
Provisioning Services test mode allows you to boot machines with an updated image in a test catalog. After you verify
its stability, you can promote the test version of the personal vDisk to production.
A new feature enables you to calculate the delta between two inventories during an inventory, instead of calculating it
for each PvD desktop. New commands are provided to export and import a previous inventory for MCS catalogs.
(Provisioning Services master vDisks already have the previous inventory.)
Known issues from 7.1.3 fixed in version 7.6:
Interrupting a personal vDisk installation upgrade can result in corrupting an existing personal vDisk installation.
[#424878]
A virtual desktop may become unresponsive if the personal vDisk runs for an extended period of time and a non-page
memory leak occurs. [#473170]
New known issues in version 7.6:
T he presence of antivirus products can affect how long it takes to run the inventory or perform an update. Performance
can improve if you add CtxPvD.exe and CtxPvDSvc.exe to the PROCESS exclusion list of your antivirus product. T hese
files are located in C:\Program Files\Citrix\personal vDisk\bin. [#326735]
Hard links between files inherited from the master image are not preserved in personal vDisk catalogs. [#368678]
After upgrading from Office 2010 to 2013 on the Personal vDisk master image, Office might fail to launch on virtual
machines because the Office KMS licensing product key was removed during the upgrade. As a workaround, uninstall
Office 2010 and reinstall Office 2013 on the master image. [#391225]
Personal vDisk catalogs do not support VMware Paravirtual SCSI (PVSCSI) controllers. T o prevent this issue, use the
default controller. [#394039]
For virtual desktops that were created with Personal vDisk version 5.6.0 and are upgraded to 7, users who logged on to
the master virtual machine (VM) previously might not find all their files in their pooled VM. T his issue occurs because a
new user profile is created when they log on to their pooled VM. T here is no workaround for this issue. [#392459]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.248
Personal vDisks running Windows 7 cannot use the Backup and Restore feature when the Windows system protection
feature is enabled. If system protection is disabled, the user profile is backed up, but the userdata.v2.vhd file is not. Citrix
recommends disabling system protection and using Backup and Restore to back up the user profile. [#360582]
When you create a VHD file on the base VM using the Disk Management tool, you might be unable to mount the VHD.
As a workaround, copy the VHD to the PvD volume. [#355576]
Office 2010 shortcuts remain on virtual desktops after this software is removed. T o work around this issue, delete the
shortcuts. [#402889]
When using Microsoft Hyper-V, you cannot create a catalog of machines with personal vDisks when the machines are
stored locally and the vDisks are stored on Cluster Shared Volumes (CSVs); catalog creation fails with an error. T o work
around this issue, use an alternative storage setup for the vDisks. [#423969]
When you log on for the first time to a virtual desktop that is created from a Provisioning Services catalog, the desktop
prompts for a restart if the personal vDisk has been reset (using the command ctxpvd.exe -s reset). T o work around this
issue, restart the desktop as prompted. T his is a once-only reset that is not required when you log on again. [#340186]
If you install .NET 4.5 on a personal vDisk and a later image update installs or modifies .NET 4.0, applications that are
dependent on .NET 4.5 fail. T o work around this issue, distribute .NET 4.5 from the base image as an image update.”
See also the
— Known Issues
documentation for the XenApp and XenDesktop 7.6 release.
Known issues from 7.1.1 fixed in version 7.1.3:
Direct upgrades from personal vDisk 5.6.0 to personal vDisk 7.x may cause the personal vDisk to fail. [#432992]
Users might only be able to connect intermittently to virtual desktops with personal vDisks. [#437203]
If a personal vDisk image update operation is interrupted while personal vDisk 5.6.5 or later is upgraded to personal vDisk
7.0 or later, subsequent update operations can fail. [#436145]
Known issues from 7.1 fixed in version 7.1.1:
Upgrading to Symantec Endpoint Protection 12.1.3 through an image update causes symhelp.exe to report corrupt
antivirus definitions. [#423429]
Personal vDisk can cause pooled desktops to restart if Service Control Manager (services.exe) crashes. [#0365351]
New known issues in version 7.1.1: none
New in version 7.1:
You can now use Personal vDisk with desktops running Windows 8.1, and event logging has been improved.
Copy-on-Write (CoW) is no longer supported. When upgrading from Version 7.0 to 7.1 of Personal vDisk, all changes to
data managed by CoW are lost. T his was a feature for evaluation in XenDesktop 7 and was disabled by default, so if you
did not enable it, you are not affected.
Known issues from 7.0.1 fixed in version 7.1:
If the value of the Personal vDisk registry key EnableProfileRedirection is set to 1 or ON, and later, while updating the
image, you change it to 0 or OFF, the entire Personal vDisk space might get allocated to user-installed applications,
leaving no space for user profiles, which remain on the vDisk. If this profile redirection is disabled for a catalog and you
enable it during an image update, users might not be able to log on to their virtual desktop. [#381921]
T he Desktop Service does not log the correct error in the Event Viewer when a Personal vDisk inventory update fails.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.249
[#383331]
When upgrading to Personal vDisk 7.x, modified rules are not preserved. T his issue has been fixed for upgrades from
Version 7.0 to Version 7.1. When upgrading from Version 5.6.5 to Version 7.1, you must first save the rule file and then
apply the rules again after the upgrade. [#388664]
Personal vDisks running Windows 8 cannot install applications from the Windows Store. An error message stating, "Your
purchase couldn't be completed," appears. Enabling the Windows Update Service does not resolve this issue, which has
now been fixed. However, user-installed applications must be reinstalled after the system restarts. [#361513]
Some symbolic links are missing in Windows 7 pooled desktops with personal vDisks. As a result, applications that store
icons in C:\Users\All Users do not display these icons in the Start menu. [#418710]
A personal vDisk does not start if an Update Sequence Number (USN) journal overflow occurs due to a large number of
changes made to the system after an inventory update. [#369846]
A personal vDisk does not start with status code 0x20 and error code 0x20000028. [#393627]
Symantec Endpoint Protection 12.1.3 displays the message "Proactive T hreat Protection is malfunctioning" and this
component's Live Update Status is not available. [#390204]
New known issues in version 7.1: See the
— Known Issues
documentation for the XenDesktop 7.1 release.
New in version 7.0.1: Personal vDisk is now more robust to environment changes. Virtual desktops with personal vDisks now
register with the Delivery Controller even if image updates fail, and unsafe system shutdowns no longer put the vDisks into
a permanently disabled state. In addition, using rules files you can now exclude files and folders from the vDisks during a
deployment.
Known issues from 5.6.13 fixed in version 7.0.1:
Changes to a group's membership made by users on a pooled virtual desktop might be lost after an image update.
[#286227]
Image updates might fail with a low disk space error even if the personal vDisk has enough space. [#325125]
Some applications fail to install on virtual desktops with a personal vDisk, and a message is displayed that a restart is
required. T his is due to a pending rename operation. [#351520]
Symbolic links created inside the master image do not work on virtual desktops with personal vDisks. [#352585]
In environments that use Citrix Profile management and personal vDisk, applications that examine user profiles on a
system volume might not function properly if profile redirection is enabled. [#353661]
T he inventory update process fails on master images when the inventory is bigger than 2GB. [#359768]
Image updates fail with error code 112 and personal vDisks are corrupted even if the vDisks have enough free space for
the update. [#363003]
T he resizing script fails for catalogs with more than 250 desktops. [#363365]
Changes made by users to an environment variable are lost when an image update is performed. [#372295]
Local users created on a virtual desktop with a personal vDisk are lost when an image update is performed. [#377964]
A personal vDisk may fail to start if an Update Sequence Number (USN) journal overflow occurred due to a large number
of changes made to the system after an inventory update. T o avoid this, increase the USN journal size to a minimum of
32 MB in the master image and perform an image update. [#369846]
An issue has been identified with Personal vDisk that prevents the correct functioning of AppSense Environment
Manager registry hiving actions when AppSense is used in Replace Mode. Citrix and AppSense are working together to
resolve the issue, which is related to the behavior of the RegRestoreKey API when Personal vDisk is installed.[#0353936]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.250
When an application installed on a personal vDisk (PvD) is related to another application of the same version that is
installed on the master image, the application on the PvD could stop working after an image update. T his occurs if you
uninstall the application from the master image or upgrade it to a later version, because that action removes the files
needed by the application on the PvD from the master image. T o prevent this, keep the application containing the files
needed by the application on the PvD on the master image.
For example, the master image contains Office 2007, and a user installs Visio 2007 on the PvD; the Office applications
and Visio work correctly. Later, the administrator replaces Office 2007 with Office 2010 on the master image, and then
updates all affected machines with the updated image. Visio 2007 no longer works. To avoid this, keep Office 2007 in
the master image. [#320915]
When deploying McAfee Virus Scan Enterprise (VSE), use version 8.8 Patch 4 or later on a master image if you use
personal vDisk. [#303472]
If a shortcut created to a file in the master image stops working (because the shortcut target is renamed within PvD),
recreate the shortcut. [#367602]
Do not use absolute/hard links in a master image. [#368678]
T he Windows 7 backup and restore feature is not supported on the personal vDisk. [#360582]
After an updated master image is applied, the local user and group console becomes inaccessible or shows inconsistent
data. T o resolve the issue, reset the user accounts on the VM, which requires resetting the security hive. T his issue was
fixed in the 7.1.2 release (and works for VMs created in later releases), but the fix does not work for VMs that were
created with an earlier version and then upgraded. [#488044]
When using a pooled VM in an ESX hypervisor environment, users see a restart prompt if the selected SCSI controller
type is “VMware Paravirtual.” For a workaround, use an LSI SCSI controller type. [#394039]
After a PvD reset on a desktop created through Provisioning Services, users may receive a restart prompt after logging
on to the VM. As a workaround, restart the desktop. [#340186]
Windows 8.1 desktop users might be unable to log on to their PvD. An administrator might see message "PvD was
disabled due to unsafe shutdown" and the PvDActivation log might contain the message "Failed to load reg hive
[\Device\IvmVhdDisk00000001\CitrixPvD\Settings\RingCube.dat]." T his occurs when a user’s VM shuts down unsafely. As
a workaround, reset the personal vDisk. [#474071]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.251
Install and upgrade
Nov 28 , 20 17
Personal vDisk 7.x is supported on XenDesktop version 5.6 through the current version. T he "System requirements"
documentation for each XenDesktop version lists the supported operating systems for Virtual Delivery Agents (VDAs), and
the supported versions of hosts (virtualization resources), and Provisioning Services. For details about Provisioning Services
tasks, see the current Provisioning Services documentation.
You can install and then enable PvD components when you install or upgrade a VDA for Desktop OS on a machine. T hese
actions are selected on the Addit ional Component s and F eat ures pages of the installation wizard, respectively. For
more information, see Install VDAs.
If you update the PvD software after installing the VDA, use the PvD MSI provided on the XenApp or XenDesktop
installation media.
Enabling PvD:
If you are using Machine Creation Services (MCS), PvD is enabled automatically when you create a machine catalog of
desktop OS machines that will use a personal vDisk.
If you are using Provisioning Services (PVS), PvD is enabled automatically when you run the inventory during the master
(base) image creation process, or when auto-update runs the inventory for you.
T herefore, if you install the PvD components but do not enable them during VDA installation, you can use the same image
to create both PvD desktops and non-PvD desktops, because PvD is enabled during the catalog creation process.
You add personal vDisks to hosts when you configure a Site. You can choose to use the same storage on the host for VMs
and personal vDisks, or you can use different storage for personal vDisks.
Later, you can also add personal vDisks and their storage to existing hosts (connections), but not machine catalogs.
1. Select Configuration > Hosting in the Studio navigation pane.
2. Select Add Personal vDisk storage in the Actions pane, and specify the storage location.
T he easiest way to upgrade personal vDisk from an earlier 7.x version is to simply upgrade your desktop OS VDAs to the
version provided with the most recent XenDesktop version. T hen, run the PvD inventory.
You can use one of two ways to remove the PvD software:
Uninstall the VDA; this removes the PvD software as well.
If you updated PvD using the PvD MSI, then you can uninstall it from the Programs list.
If you uninstall PvD and then want to reinstall the same or a newer version, first back up the registry key
HKLM\Software\Citrix\personal vDisk\config, which contains environment configuration settings that might have changed.
T hen, after installing PvD, reset the registry values that might have changed, by comparing them with the backed-up
version.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.252
Import ant considerat ions when uninst alling P vD
Uninstalling may fail when a personal vDisk with Windows 7 (64 bit) is installed in the base image. To resolve this issue, Citrix
recommends that you remove the personal vDisk before upgrading:
1. Select the appropriate copy of the vDisk installer from the XenApp/XenDesktop media. Locate the latest personal vDisk
MSI installer from the XenApp/XenDesktop ISO from one of the following directories (depending on whether the upgraded
VM is 32 or 64-bits):
32-bits: XA and XD\x86\Virtual Desktop Components\personalvDisk_x86.msi
64-bits: XA and XD\x64\Virtual Desktop Components\personalvDisk_x64.msi
2. Remove the personal vDisk installation. Select the personal vDisk MSI installer package found in step 1. T he personal
vDisk setup screen appears.
3. Select Remove personal vDisk.
4. Click F inish .
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.253
5. T he Reboot Requirement page appears. Click Next :
6. Click Yes to restart the system and to apply your configuration changes:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.254
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.255
Configure and manage
Nov 28 , 20 17
T his topic covers items you should consider when configuring and managing a personal vDisk (PvD) environment. It also
covers best practice guidelines and task descriptions.
For procedures that include working in the Windows registry:
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 Registry Editor can be solved. Use Registry Editor
at your own risk. Be sure to back up the registry before you edit it.
T he following factors affect the size of the main personal vDisk volume:
Size of t he applicat ions t hat users will inst all on t heir P vDs
At restarts, PvD determines the free space remaining in the application area (UserData.v2.vhd). If this falls below 10%, the
application area is expanded into any unused profile area space (by default, the space available on the P: drive). T he
space added to the application area is approximately 50% of the combined free space remaining in both the application
area and the profile area.
For example, if the application area on a 10 GB PvD (which by default is 5 GB) reaches 4.7 GB and the profile area has 3
GB free, the increased space that is added to the application area is calculated as follows:
increased space = (5.0-4.7)/2 + 3.0/2 = 1.65 GB
T he space added to the application area is only approximate because a small allowance is made for storing logs and for
overhead. T he calculation and the possible resizing is performed on each restart.
Size of users' prof iles (if a separat e prof ile management solut ion is not used)
In addition to the space required for applications, ensure there is sufficient space available on personal vDisks to store
users' profiles. Include any non-redirected special folders (such as My Documents and My Music) when calculating space
requirements. Existing profile sizes are available from the Control Panel (sysdm.cpl).
Some profile redirection solutions store stub files (sentinel files) instead of real profile data. T hese profile solutions might
appear to store no data initially but actually consume one file directory entry in the file system per stub file; generally,
approximately 4 KB per file. If you use such a solution, estimate the size based on the real profile data, not the stub files.
Enterprise file sharing applications (such as ShareFile and Dropbox) might synchronize or download data to users' profile
areas on the personal vDisks. If you use such applications, include enough space in your sizing estimates for this data.
Overhead consumed by t he t emplat e VHD cont aining t he P vD invent ory
T he template VHD contains the PvD inventory data (sentinel files corresponding to the master image content). T he PvD
application area is created from this VHD. Because each sentinel file or folder comprises a file directory entry in the file
system, the template VHD content consumes PvD application space even before any applications are installed by the
end user. You can determine the template VHD size by browsing the master image after an inventory is taken.
Alternatively, use the following equation for an approximately calculation:
template VHD size = (number of files on base image) x 4 KB
Determine the number of files and folders by right-clicking the C: drive on the base VM image and selecting Properties.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.256
For example, an image with 250,000 files results in a template VHD of approximately 1,024,000,000 bytes (just under 1
GB). T his space will be unavailable for application installations in the PvD application area.
Overhead f or P vD image updat e operat ions
During PvD image update operations, enough space must be available at the root of the PvD (by default, P:) to merge
the changes from the two image versions and the changes the user has made to their PvD. Typically, PVD reserves a few
hundred megabytes for this purpose, but extra data that was written to the P: drive might consume this reserved space,
leaving insufficient space for the image update to complete successfully. T he PvD pool statistics script (located on the
XenDesktop installation media in the Support/Tools/Scripts folder) or the PvD Image Update Monitoring Tool (in the
Support/Tools/Scripts\PvdTool folder) can help identify any PvD disks in a catalog that are undergoing an update and
that are nearly full.
T he presence of antivirus products can affect how long it takes to run the inventory or perform an update. Performance
can improve if you add CtxPvD.exe and CtxPvDSvc.exe to the exclusion list of your antivirus product. T hese files are
located in C:\Program Files\Citrix\personal vDisk\bin. Excluding these executables from scanning by the antivirus
software can improve inventory and image update performance by up to a factor of ten.
Overhead f or unexpect ed growt h (unexpect ed applicat ion inst allat ions, and so on)
Consider allowing extra (either a fixed amount or a percentage of the vDisk size) to the total size to accommodate
unexpected application installations that the user performs during deployment.
You can manually adjust the automatic resizing algorithm that determines the size of the VHD relative to the P: drive, by
setting the initial size of the VHD. T his can be useful if, for example, you know users will install a number of applications
that are too big to fit on the VHD even after it is resized by the algorithm. In this case, you can increase the initial size of
the application space to accommodate the user-installed applications.
Preferably, adjust the initial size of the VHD on a master image. Alternatively, you can adjust the size of the VHD on a
virtual desktop when a user does not have sufficient space to install an application. However, you must repeat that
operation on each affected virtual desktop; you cannot adjust the VHD initial size in a catalog that is already created.
Ensure the VHD is big enough to store antivirus definition files, which are typically large.
Locate and set the following registry keys in HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\personal vDisk\Config. (Do not
modify other settings in this registry key.) All settings must be specified on the master image (except for
MinimumVHDSizeInMB, which can be changed on an individual machine); settings specified on the master image are applied
during the next image update.
MinimumVHDSizeMB
Specifies the minimum size (in megabytes) of the application part (C:) of the personal vDisk. T he new size must be greater
than the existing size but less than the size of the disk minus PvDReservedSpaceMB.
Increasing this value allocates free space from the profile part on the vDisk to C:. T his setting is ignored if a lower value
than the current size of the C: drive is used, or if EnableDynamicResizeOfAppContainer is set to 0.
Default = 2048
EnableDynamicResizeOf AppCont ainer
Enables or disables the dynamic resizing algorithm.
When set to 1, the application space (on C:) is resized automatically when the free space on C: falls below 10%.
Allowed values are 1 and 0. A restart is required to effect the resize.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.257
When set to 0, the VHD size is determined according to the method used in XenDesktop versions earlier than 7.x
Default = 1
EnableUserP rof ileRedirect ion
Enables or disables redirecting the user's profile to the vDisk.
When set to 1, PvD redirects users' profiles to the personal vDisk drive (P: by default). Profiles are generally redirected
to P:\Users, corresponding to a standard Windows profile. T his redirection preserves the profiles in case the PvD
desktop must be reset.
When set to 0, all of the space on the vDisk minus PvDReservedSpaceMB is allocated to C:, the application part of
the vDisk, and the vDisk drive (P:) is hidden in Windows Explorer. Citrix recommends disabling redirection by setting the
value to 0, when using Citrix Profile management or another roaming profile solution.
T his setting retains the profiles in C:\Users instead of redirecting them to the vDisk, and lets the roaming profile
solution handle the profiles.
T his value ensures that all of the space on P: is allocated to applications.
It is assumed that if this value is set to 0, a profile management solution is in place. Disabling profile redirection
without a roaming profile solution in place is not recommended because subsequent PvD reset operations result in
the profiles being deleted.
Do not change this setting when the image is updated because it does not change the location of existing profiles, but
it will allocate all the space on the Personal vDisk to C: and hide the PvD.
Configure this value before deploying a catalog. You cannot change it after the catalog is deployed.
Important: Beginning with XenDesktop 7.1, changes to this value are not honored when you perform an image update.
Set the key's value when you first create the catalogs from which the profiles will originate. You cannot modify the
redirection behavior later.
Default = 1
P ercent Of P vDF orApps
Sets the split between the application part (C:) and the profile part of the vDisk. T his value is used when creating new
VMs, and during image updates when EnableDynamicResizeOfAppContainer is set to 0.
Changing PercentOfPvDForApps makes a difference only when EnableDynamicResizeOfAppContainer is set to 0. By
default, EnableDynamicResizeOfAppContainer is set to 1 (enabled), which means is that the AppContainer (which you
see as the C drive) only expands when it is close to being full (that is, dynamic) - when less than 10% free space remains.
Increasing PercentOfPvDForApps only increases the maximum space for which the Apps portion is allowed to expand. It
does not provision that space for you immediately. You must also configure the split allocation in the master image,
where it will be applied during the next image update.
If you have already generated a catalog of machines with EnableDynamicResizeOfAppContainer set to 1, then change
that setting to 0 in the master image for the next update, and configure an appropriate allocation split. T he requested
split size will be honored as long as it is larger than the current allocated size for the C drive.
If you want to maintain complete control over the space split, set this value to 0. T his allows full control over the C drive
size, and does not rely on a user consuming space below the threshold to expand the drive.
Default = 50% (allocates equal space to both parts)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.258
P vDReservedSpaceMB
Specifies the size of the reserved space (in megabytes) on the vDisk for storing Personal vDisk logs and other data.
If your deployment includes XenApp 6.5 (or an earlier version) and uses application streaming, increase this value by the
size of the Rade Cache.
Default = 512
P vDReset UserGroup
Valid only for XenDesktop 5.6 - Allows the specified group of users to reset a Personal vDisk. Later XenDesktop releases
use Delegated Administration for this.
Other settings:
Windows Updat e Service - Ensure that you set Windows updates to Never Check for Update and the Windows
update service to Disabled in the master image. In the event Windows Update Service needs to run on the PvD, setting it
to Never Check for Update helps prevent the updates from being installed on the associated machines.
Windows 8 Store needs this service to run to install any Modern-style application.
Windows updat es - T hese include Internet Explorer updates and must be applied on the master image.
Updat es requiring rest art s - Windows updates applied to the master image might require multiple restarts to fully
install, depending on the type of patches delivered in those updates. Ensure you restart the master image properly to
fully complete the installation of any Windows updates applied to it before taking the PvD inventory.
Applicat ion updat es - Update applications installed on the master image to conserve space on users' vDisks. T his also
avoids the duplicate effort of updating the applications on each user's vDisk.
Some software might conflict with the way that PvD composites the user's environment, so you must install it on the
master image (rather than on the individual machine) to avoid these conflicts. In addition, although some other software
might not conflict with the operation of PvD, Citrix recommends installing it on the master image.
Applications that must be installed on the master image:
Agents and clients (for example, System Center Configuration Manager Agent, App-V client, Citrix Receiver)
Applications that install or modify early-boot drivers
Applications that install printer or scanner software or drivers
Applications that modify the Windows network stack
VM tools such as VMware T ools and XenServer T ools
Applications that should be installed on the master image:
Applications that are distributed to a large number of users. In each case, turn off application updates before
deployment:
Enterprise applications using volume licensing, such as Microsoft Office, Microsoft SQL Server
Common applications, such as Adobe Reader, Firefox, and Chrome
Large applications such as SQL Server, Visual Studio, and application frameworks such as .NET
T he following recommendations and restrictions apply to applications installed by users on machines with personal vDisks.
Some of these cannot be enforced if users have administrative privileges:
Users should not uninstall an application from the master image and reinstall the same application on their personal
vDisk.
T ake care when updating or uninstalling applications on the master image. After you install a version of an application on
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.259
the image, a user might install an add-on application (for example, a plug-in) that requires this version. If such a
dependency exists, updating or uninstalling the application on the image might make the add-on malfunction. For
example, with Microsoft Office 2010 installed on a master image, a user installs Visio 2010 on their personal vDisk. A later
upgrade of Office on the master image might make the locally-installed Visio unusable.
Software with hardware-dependent licenses (either through a dongle or signature-based hardware) is unsupported.
When using Provisioning Services with PvD:
T he Soap Service account must be added to the Administrator node of Studio and must have the Machine Administrator
or higher role. T his ensures that the PvD desktops are put into the Preparing state when the Provisioning Services (PVS)
vDisk is promoted to production.
T he Provisioning Service versioning feature must be used to update the personal vDisk. When the version is promoted to
production, the Soap Service puts the PvD desktops into the Preparing state.
T he personal vDisk size should always be larger than the Provisioning Services write cache disk (otherwise, Provisioning
Services might erroneously select the personal vDisk for use as its write cache).
After you create a Delivery Group, you can monitor the personal vDisk using the PvD Image Update Monitoring T ool or
the Resize and poolstats scripts (personal-vdisk-poolstats.ps1).
Size the write cache disk correctly. During normal operation, PvD captures most user writes (changes) and redirects them to
the personal vDisk. T his implies that you can reduce the size of the Provisioning Services write cache disk. However, when
PvD is not active (such as during image update operations), a small Provisioning Services write cache disk can fill up, resulting
in machine crashes.
Citrix recommends that you size Provisioning Services write cache disks according to Provisioning Services best practice and
add space equal to twice the size of the template VHD on the master image (to accommodate merge requirements). It is
extremely unlikely that a merge operation will require all of this space, but it is possible.
When using Provisioning Services to deploy a catalog with PvD-enabled machines:
Follow the guidance in the Provisioning Services documentation.
You can change the power action throttling settings by editing the connection in Studio; see below.
If you update the Provisioning Services vDisk, after you install/update applications and other software and restart the
vDisk, run the PvD inventory and then shut down the VM. T hen, promote the new version to Production. T he PvD
desktops in the catalog should automatically enter the Preparing state. If they do not, check that the Soap Service
account has machine administrator or higher privileges on the Controller.
T he Provisioning Services test mode feature enables you to create a test catalog containing machines using an updated
master image. If tests confirm the test catalog's viability, you can promote it to production.
When using Machine Creation Services (MCS) to deploy a catalog with PvD-enabled machines:
Follow the guidance in the XenDesktop documentation.
Run a PvD inventory after you create the master image and then power off the VM (PvD will not function correctly if
you do not power off the VM). T hen, take a snapshot of the master image.
In the Create Machine Catalog wizard, specify the personal vDisk size and drive letter.
After you create a Delivery Group, you can monitor the personal vDisk using the PvD Image Update Monitoring T ool or
the Resize and poolstats scripts (personal-vdisk-poolstats.ps1).
You can change the power action throttling settings by editing the connection in Studio; see below.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.260
If you update the master image, run the PvD inventory after you update the applications and other software on the
image, and then power off the VM. T hen, take a snapshot of the master image.
Use the PvD Image Update Monitoring T ool or the personal-vdisk-poolstats.ps1 script to validate that there is sufficient
space on each PvD-enabled VM that will use the updated master image.
After you update the machine catalog, the PvD desktops enter the Preparing state as they individually process the
changes in the new master image. T he desktops are updated according to the rollout strategy specified during the
machine update.
Use the PvD Image Update Monitoring T ool or the personal-vdisk-poolstats.ps1 script to monitor the PvD in the
Preparing state.
Use the rules files to exclude files and folders from the vDisks. You can do this when the personal vDisks are in deployment.
T he rules files are named custom_*_rules.template.txt and are located in the \config folder. Comments in each file provide
additional documentation.
When you enable PvD and after any update to the master image after installation, it is important to refresh the disk's
inventory (called "run the inventory") and create a new snapshot.
Because administrators, not users, manage master images, if you install an application that places binary files in the
administrator's user profile, the application is not available to users of shared virtual desktops (including those based on
pooled machine catalogs and pooled with PvD machine catalogs). Users must install such applications themselves.
It is best practice to take a snapshot of the image after each step in this procedure.
1. Update the master image by installing any applications or operating system updates, and performing any system
configuration on the machine.
For master images based on Windows XP that you plan to deploy with Personal vDisks, check that no dialog boxes are
open (for example, messages confirming software installations or prompts to use unsigned drivers). Open dialog boxes on
master images in this environment prevent the VDA from registering with the Delivery Controller. You can prevent
prompts for unsigned drivers using the Control Panel. For example, navigate to System > Hardware > Driver Signing, and
select the option to ignore warnings.
2. Shut down the machine. For Windows 7 machines, click Cancel when Citrix Personal vDisk blocks the shutdown.
3. In the Citrix Personal vDisk dialog box, click Update Inventory. T his step may take several minutes to complete.
Important: If you interrupt the following shutdown (even to make a minor update to the image), the Personal vDisk's
inventory no longer matches the master image. T his causes the Personal vDisk feature to stop working. If you interrupt
the shutdown, you must restart the machine, shut it down, and when prompted click Update Inventory again.
4. When the inventory operation shuts down the machine, take a snapshot of the master image.
You can export an inventory to a network share and then import that inventory to a master image. For details, see Export
and import a PvD inventory.
T he Citrix Broker Service controls the power state of the machines that provide desktops and applications. T he Broker
Service can control several hypervisors through a Delivery Controller. Broker power actions control the interaction between
a Controller and the hypervisor. To avoid overloading the hypervisor, actions that change a machine’s power state are
assigned a priority and sent to the hypervisor using a throttling mechanism. T he following settings affect the throttling. You
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.261
specify these values by editing a connection (Advanced page) in Studio.
T o configure connection throttling values:
1. Select Configuration > Hosting in the Studio navigation pane.
2. Select the connection and then select Edit Connection in the Actions pane.
3. You can change the following values:
Simult aneous act ions (all t ypes) - T he maximum number of simultaneous in-progress power actions allowed. T his
setting is specified as both an absolute value and as a percentage of the connection to the hypervisor. T he lower of
the two values is used.
Default = 100 absolute, 20%
Simult aneous P ersonal vDisk invent ory updat es - T he maximum number of simultaneous Personal vDisk power
actions allowed. T his setting is specified as both an absolute value and a percentage of the connection. T he lower of
the two values is used.
Default = 50 absolute, 25%
To calculate the absolute value: determine the total IOPS (T IOPS) supported by the end-user storage (this should be
specified by the manufacturer or calculated). Using 350 IOPS per VM (IOPS/VM), determine the number of VMs that
should be active at any given time on the storage. Calculate this value by dividing total IOPS by IOPS/VM.
For example, if the end-user storage is 14000 IPS, the number of active VMs is 14000 IOPS / 350 IOPS/VM = 40.
Maximum new act ions per minut e - T he maximum number of new power actions that can be sent to the
hypervisor per minute. Specified as an absolute value.
Default = 10
T o help identify optimal values for these settings in your deployment:
1. Using the default values, measure the total response time for an image update of a test catalog. T his is the difference
between the start of an image update (T 1) and when the VDA on the last machine in the catalog registers with the
Controller (T 2). T otal response time = T 2 - T 1.
2. Measure the input/output operations per second ( IOPS) of the hypervisor storage during the image update. T his data
can serve as a benchmark for optimization. (T he default values may be the best setting; alternatively, the system might
max out of IOPS, which will require lowering the setting values.)
3. Change the “Simultaneous Personal vDisk inventory updates” value as described below (keeping all other settings
unchanged).
1. Increase the value by 10 and measure the total response time after each change. Continue to increase the value by
10 and test the result, until deterioration or no change in the total response time occurs.
2. If the previous step resulted in no improvement by increasing the value, decrease the value in increments of 10 and
measure the total response time after each decrease. Repeat this process until the total response time remains
unchanged or does not improve further. T his is likely the optimal PvD power action value.
4. After obtaining the PvD power action setting value, tweak the simultaneous actions (all types) and maximum new
actions per minute values, one at a time. Follow the procedure described above (increasing or decreasing in increments)
to test different values.
System Center Configuration Manager (Configuration Manager) 2012 requires no special configuration and can be installed
in the same way as any other master image application. T he following information applies only to System Center
Configuration Manager 2007. Configuration Manager versions earlier than Configuration Manager 2007 are not supported.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.262
Complete the following to use Configuration Manager 2007 agent software in a PvD environment.
1. Install the Client Agent on the master image.
1. Install the Configuration Manager client on the master image.
2. Stop the ccmexec service (SMS Agent) and disable it.
3. Delete SMS or client certificates from the local computer certificate store as follows:
Mixed mode: Certificates (Local Computer)\SMS\Certificates
Native mode
Certificates (Local Computer)\Personal\Certificates
Delete the client certificate that was issued by your certificate authority (usually, an internal Public Key
Infrastructure)
4. Delete or rename C:\Windows\smscfg.ini.
2. Remove information that uniquely identifies the client.
1. (Optional) Delete or move log files from C:\Windows\System32\CCM\Logs.
2. Install the Virtual Delivery Agent (if not installed previously), and take the PvD inventory.
3. Shut down the master image, take a snapshot, and create a machine catalog using this snapshot.
3. Validate personal vDisk and start services. Complete these steps once on each PvD desktop, after it has been started for
the first time. T his can be done using a domain GPO, for example.
Confirm that PvD is active by checking for the presence of the registry key HKLM\Software\Citrix\personal
vDisk\config\virtual.
Set the ccmexec service (SMS agent) to Automatic and start the service. T he Configuration Manager client contacts
the Configuration Manager server, and retrieves new unique certificates and GUIDs.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.263
Tools
Nov 28 , 20 17
You can use the following tools and utilities to tailor, expedite, and monitor PvD operations.
T he custom rule files provided with PvD let you modify the default behavior of PvD image updates in the following ways:
T he visibility of files on the PvD
How changes made to the files are merged
Whether the files are writable
For detailed instructions on the custom rules files and the CoW feature, refer to the comments in the files located in
C:\ProgramData\Citrix\personal vDisk\Config on the machine where PvD is installed. T he files named "custom_*" describe
the rules and how to enable them.
Two scripts are provided to monitor and manage the size of PvDs; they are located in the Support\Tools\Scripts folder on
the XenDesktop installation media. You can also use the PvD Image Update Monitoring Tool, which is located in the
Support\Tools\Scripts\PvdTool folder; see http://blogs.citrix.com/2014/06/02/introducing-the-pvd-image-updatemonitoring-tool/ for details.
Use resize-personalvdisk-pool.ps1 to increase the size of the PvDs in all of the desktops in a catalog. T he following snap-ins
or modules for your hypervisor must be installed on the machine running Studio:
XenServer requires XenServerPSSnapin
vCenter requires vSphere PowerCli
System Center Virtual Machine Manager requires the VMM console
Use personal-vdisk-poolstats.ps1 to check the status of image updates and to check the space for applications and user
profiles in a group of PvDs. Run this script before updating an image to check whether any desktop is running out of space,
which helps prevent failures during the update. T he script requires that Windows Management Instrumentation (WMI-In)
firewall is enabled on the PvD desktops. You can enable it on the master image or through GPO.
If an image update fails, the entry in the Update column gives the reason.
If a desktop becomes damaged or corrupted (by installing a broken application or some other cause), you can revert the
application area of the PvD to a factory-default (empty) state. T he reset operation leaves user profile data intact.
T o reset the application area of the PvD, use one of the following methods:
Log on to the user's desktop as Administrator. Launch a command prompt, and run the command C:\Program
Files\Citrix\Personal vDisk\bin\CtxPvD.exe -s Reset.
Locate the user's desktop in Citrix Director. Click Reset Personal vDisk and then click OK.
T he image update process is an integral part of rolling out new images to PvD desktops; it includes adjusting the existing
Personal vDisk to work with the new base image. For deployments that use Machine Creations Services (MCS), you can
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.264
export an inventory from an active VM to a network share, and then import it into a master image. A differential is
calculated using this inventory in the master image. Although using the export/import inventory feature is not mandatory, it
can improve the performance of the overall image update process.
T o use the export/import inventory feature, you must be an administrator. If required, authenticate to the file share used
for the export/import with “net use.” T he user context must be able to access any file shares used for the export/import.
T o export an inventory, run the export command as an administrator on a machine containing a VDA with PvD enabled
(minimum version 7.6):
Ctxpvdsvc.exe exportinventory “<path-to-export-location>”
T he software detects the current inventory’s location and exports the inventory to a folder named
“ExportedPvdInventory” to the specified location. Here’s an excerpt from the command output:
C:\Program Files\Citrix\personal vDisk\bin> .\CtxPvDSvc.exe exportinventory
\\share location\ExportedInventory
Current inventory source location C:\CitrixPvD\Settings\Inventory\VER-LAS
...
Exporting current inventory to location \\ ….
...
Deleting any pre-existing inventory folder at \\ ….
.Successfully exported current inventory to location \\ …. Error code = OPS
T o import a previously-exported inventory, run the import command as an administrator on the master image:
To import
Run the import command as an administrator on the master image.
Ctxpvdsvc.exe importinventory “<path-to-exported-inventory>”
T he <path to exported inventory> should be the full path to the inventory files, which is usually <network
location\ExportedPvdInventory>.
T he inventory is obtained from the import location (where it was previously exported using the exportinventory option) and
imports the inventory to the inventory store on the master image. Here’s an excerpt of the command output:
C:\Program Files\Citrix\personal vDisk\bin> .\CtxPvDSvc.exe importinventory
\\share location\ExportedInventory\ExportedPvdInventory
Importing inventory \\share location\ExportedInventory\ExportedPvdInventory
…
Successfully added inventory \\share location\ExportedInventory\ExportedPvdInventory to the
store at c:\ProgramData\Citrix\personal vDisk\InventoryStore
After the export, the network share should include the following filenames. After the import, the inventory store on the
master image should include the same file names.
Components.DAT
files_rules
folders_rules
regkey_rules
RINGT HREE.DAT
S-1-5-18.DAT
SAM.DAT
SECURIT Y.DAT
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.265
SNAPSHOT .DAT
SOFT WARE.DAT
SYST EM.CurrentControlSet.DAT
VDCAT ALOG.DAT
vDiskJournalData
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.266
Displays, messages, and troubleshooting
Nov 28 , 20 17
Monitor PvD through reports
You can use a diagnostic tool to monitor the changes made by users to both parts of their Personal vDisks (the user data
and the application parts). T hese changes include applications that users have installed and files they have modified. T he
changes are stored in a set of reports.
1. On the machine you want to monitor, run C:\P rogram F iles\Cit rix\personal vDisk\bin\Ct xP vdDiag.exe .
2. Browse to a location where you want to store the reports and logs, select the reports to generate, and then
click OK . T he available reports are listed below.
Sof t ware hive report : T his report generates two files: Software.Dat.Report.txt and Software.Dat.delta.txt.
T he Software.Dat.Report.txt file records the changes made by the user to the HKEY_LOCAL_MACHINE\Software hive. It
contains the following sections:
List of Applications installed on the base — Applications that were installed in Layer 0.
List of user installed software — Applications the user installed on the application part of the personal vDisk.
List of software uninstalled by user — Applications the user removed that were originally in Layer 0.
See the hive delta report for information about the Software.Dat.delta.txt.
Syst em hive report : T he generated SYST EM.CurrentControlSet.DAT.Report.txt file records changes the user made to the
HKEY_LOCAL_MACHINE\System hive. It contains the following sections:
List of user installed services — services and drivers the user installed.
Startup of following services were changed — services and drivers whose start type the user modified.
Securit y hive report : T he generated SECURIT Y.DAT.Report.txt file monitors all changes that the user makes in the
HKEY_LOCAL_MACHINE\Security hive.
Securit y Account Manager (SAM) hive report : T he generated SAM.DAT.Report.txt file monitors all changes that the
user makes in the HKEY_LOCAL_MACHINE\SAM hive.
Hive delt a report : T he generated Software.Dat.delta.txt file records all registry keys and values added or removed, and all
values the user modified in the HKEY_LOCAL_MACHINE\Software hive.
P ersonal vDisk logs: T he log files Pud-IvmSupervisor.log, PvDActivation.log, PvDSvc.log, PvDWMI.log, SysVolIvmSupervisor.log, and vDeskService-<#>.log are generated by default in P:\Users\<user
account>\AppData\Local\Temp\PVDLOGS, but are moved to the selected location.
Windows operat ing syst em logs:
EvtLog_App.xml and EvtLog_System.xml are the application and system event logs in XML format from the personal
vDisk volume.
Setupapi.app.log and setuperr.log contain log messages from when msiexec.exe was run during personal vDisk
installation.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.267
Setupapi.dev.log contains device installation log messages.
Msinfo.txt contains the output of msinfo32.exe. For information, see the Microsoft documentation.
F ile syst em report : T he generated FileSystemReport.txt file records changes the user made to the file system in the
following sections:
Files Relocated — Files in Layer 0 that the user moved to the vDisk. Layer 0 files are inherited from the master image by
the machine to which the personal vDisk is attached.
Files Removed — Files in Layer 0 that were hidden by a user's action (for example, removing an application).
Files Added (MOF,INF,SYS) — Files with .mof, .inf, or .sys extensions that the user added to the personal vDisk (for
example, when they installed an application such as Visual Studio 2010 that registers a .mof file for autorecovery).
Files Added Other — Other files that the user added to the vDisk (for example, when installing an application).
Base Files Modified But Not Relocated — Files in Layer 0 that the user modified but that the personal vDisk KernelMode drivers did not capture in the vDisk.
Image updates
In Studio, when you choose a PvD-enabled machine in a machine catalog, the "PvD" tab provides monitoring status during
image updates, plus estimated completion time and progress. T he possible state displays during an image update are: Ready,
Preparing, Waiting, Failed, and Requested.
An image update can fail for different reasons, including lack of space or a desktop not finding the PvD in sufficient time.
When Studio indicates that an image update failed, an error code with descriptive text is provided to help troubleshooting.
Use the Personal vDisk Image Update Monitoring Tool or the personal-vdisk-poolstats.ps1 script to monitor image update
progress and obtain error codes associated with the failure.
If an image update fails, the following log files can provide further troubleshooting information:
PvD service log - C:\ProgramData\Citrix\personal vDisk\Logs\PvDSvc.log.txt
PvD activation log i- P:\PVDLOGS\PvDActivation.log.txt
T he most recent content is at the end of the log file.
T he following errors are valid for PvD version 7.6 and later:
An int ernal error occurred. Review t he P ersonal vDisk logs f or f urt her det ails. Error code % d (% s)
T his is a catch-all for uncategorized errors, so it has no numeric value. All unexpected errors encountered during inventory
creation or Personal vDisk update are indicated by this error code.
Collect logs and contact Citrix support.
If this error occurs during catalog update, roll back the catalog to the previous version of the master image.
T here are synt ax errors in t he rule f iles. Review t he logs f or f urt her det ails.
Error code 2. T he rule file contains syntax errors. T he Personal vDisk log file contains the name of the rule file and line
number where the syntax error was found. Fix the syntax error in the rule file and retry the operation.
T he invent ory st ored in t he P ersonal vDisk corresponding t o t he previous version of t he mast er image is
corrupt or unreadable.
Error code 3. T he last inventory is stored in “UserData.V2.vhd” in “\ProgramData\CitrixPvD\Settings\Inventory\VERLAST ”. Restore the inventory corresponding to the last version of the master image by importing the ‘VER-LAST ’ folder
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.268
from a known working PvD machine associated with the previous version of the master image.
T he invent ory st ored in t he P ersonal vDisk corresponding t o t he previous version of t he mast er image is
higher version.
Error code 4. T his is caused by personal vDisk version incompatibility between the last master image and the current
master image. Retry updating the catalog after installing the latest version of personal vDisk in the master image.
Change journal overf low was det ect ed.
Error code 5. A USN journal overflow was caused by a large number of changes made to the master image while creating
the inventory. If this continues to occur after multiple attempts, use procmon to determine if third party software is
creating/deleting a large number of files during inventory creation.
T he P ersonal vDisk could not f ind a disk at t ached t o t he syst em f or st oring user dat a.
Error code 6. First, verify that the PvD disk is attached to the VM through the hypervisor console. T his error typically
happens due to “Data Leak Prevention” software preventing access to the PvD disk. If the PvD disk is attached to the
VM, try adding an exception for “attached disk” in the “Data Leak Prevention” software configuration.
T he syst em has not been reboot ed post -inst allat ion. Reboot t o implement t he changes.
Error code 7. Restart the desktop and retry the operation.
Corrupt inst allat ion. T ry re-inst alling P ersonal vDisk.
Error code 8. Install personal vDisk and try again.
P ersonal vDisk invent ory is not up t o dat e. Updat e t he invent ory in t he mast er image, and t hen t ry again.
Error code 9. T he personal vDisk inventory was not updated in the master image before shutting down the desktop.
Restart the master image and shut down the desktop through the “Update personal vDisk” option, and then create a
new snapshot; use that snapshot to update the catalog.
An int ernal error occurred while st art ing t he P ersonal vDisk. Review t he P ersonal vDisk logs f or f urt her
det ails.
Error code 10. T his could be caused by the PvD driver failing to start a virtualization session due to an internal error or
personal vDisk corruption. Try restarting the desktop through the Controller. If the problem persists, collect the logs and
contact Citrix Support.
T he P ersonal vDisk t imed out while t rying t o f ind a st orage disk f or users' personalizat ion set t ings.
Error code 11. T his error occurs when the PvD driver fails to find the PvD disk within 30 seconds after restart. T his is
usually caused by an unsupported SCSI controller type or storage latency. If this occurs with all desktops in the catalog,
change the SCSI controller type associated with the “Template VM” / “Master VM” to a type supported by personal
vDisk technology. If this occurs with only some desktops in the catalog, it might be due to spikes in storage latency due
to a large number of desktops starting at the same time. Try limiting the maximum active power actions setting
associated with the host connection.
T he P ersonal vDisk has been de-act ivat ed because an unsaf e syst em shut down was det ect ed. Rest art t he
machine.
Error code 12. T his could be due to a desktop failing to complete the boot process with PvD enabled. Try restarting the
desktop. If the problem persists, watch the desktop startup through the hypervisor console and check if the desktop is
crashing. If a desktop crashes during startup, restore the PvD from backup (if you maintain one) or reset the PvD.
T he drive let t er specif ied f or mount ing t he P ersonal vDisk is not available.
Error code 13. T his could be caused by PvD failing to mount the PvD disk at the mount specified by the administrator.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.269
T he PvD disk will fail to mount if the drive letter is already used by other hardware. Select a different letter as the mount
point for the personal vDisk.
P ersonal vDisk kernel mode drivers f ailed t o inst all.
Error code 14. Personal vDisk installs drivers during the first inventory update after installation. Some antivirus products
prevent installation of the driver when attempted outside the context of an installer. Temporarily disable the antivirus
real time scan or add exceptions in the antivirus for PvD drivers during the first time inventory creation.
Cannot creat e a snapshot of t he syst em volume. Make sure t hat t he Volume Shadow Copy service is
enabled.
Error code 15. T his could occur because the Volume Shadow Copy service is disabled. Enable the Volume Shadow Copy
service and retry taking an inventory.
T he change journal f ailed t o act ivat e. T ry again af t er wait ing f or f ew minut es.
Error code 16. Personal vDisk uses change journal for tracking changes made to master image. During an inventory
update, if PvD detects that the change journal is disabled, it attempts to enable it; this error occurs when that attempt
fails. Wait for few minutes and retry.
T here is not enough f ree space in t he syst em volume.
Error code 17. T here is not enough free space available on the C drive of the desktop for the image update operation.
Expand the system volume or remove unused files to free space in the system volume. T he image update should begin
again after the next restart.
T here is not enough f ree space in t he P ersonal vDisk st orage. Expand P ersonal vDisk st orage t o provide
more space.
Error code 18. T here is not enough free space available on the personal vDisk drive when performing an image update
operation. Expand personal vDisk storage or remove unused files to free space in the personal vDisk storage. T he image
update should restart after next reboot.
P ersonal vDisk st orage is over-commit t ed. Expand P ersonal vDisk st orage t o provide more space.
Error code 19. T here is not enough free space available on the personal vDisk drive to fully accommodate thick
provisioned “UserData.V2.vhd”. Expand the personal vDisk storage or remove unused files to free space in the personal
vDisk storage.
Corrupt syst em regist ry.
Error code 20. T he system registry is corrupt, damaged, missing, or unreadable. Reset the personal vDisk or restore it from
an earlier backup.
An int ernal error occurred while reset t ing t he P ersonal vDisk. Check P ersonal vDisk logs f or f urt her det ails.
Error code 21. T his is a catch-all for all the errors encountered during a personal vDisk reset. Collect the logs and contact
Citrix Support.
F ailed t o reset t he P ersonal vDisk because t here is not enough f ree space in t he personal vDisk st orage.
Error code 22. T here is not enough free space available on the Personal vDisk drive when performing a reset operation.
Expand the personal vDisk storage or remove unused files to free space in the personal vDisk storage.
T he following errors are valid for PvD 7.x versions earlier than 7.6:
St art up f ailed. P ersonal vDisk was unable t o f ind a st orage disk f or user personalizat ion set t ings.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.270
T he PvD software could not find the Personal vDisk (by default, the P: drive) or could not mount it as the mount point
selected by the administrator when they created the catalog.
Check the PvD service log for following entry: "PvD 1 status --> 18:183".
If you are using a version of PvD earlier than Version 5.6.12, upgrading to the latest version resolves this issue.
If you are using Version 5.6.12 or later, use the disk management tool (diskmgmt.msc) to determine whether the P:
drive is present as an unmounted volume. If present, run chkdsk on the volume to determine if it is corrupt, and try to
recover it using chkdsk.
St art up f ailed. Cit rix P ersonal vDisk f ailed t o st art . F or f urt her assist ance .... St at us code: 7 , Error code:
0x7 0
Status code 7 implies that an error was encountered while trying to update the PvD. T he error could be one of the
following:
Error code
Descript ion
0x20000001
Failed to save the diff package, most likely due to lack of free disk space inside the VHD.
0x20000004
Failed to acquire required privileges for updating the PvD.
0x20000006
Failed to load hive from the PvD image or from PvD inventory, most likely due to corrupt PvD image or
inventory.
0x20000007
Failed to load the file system inventory, most likely due to a corrupt PvD image or inventory.
0x20000009
Failed to open the file containing file system inventory, most likely due to a corrupt PvD image or
inventory.
0x2000000B
Failed to save the diff package, most likely due to lack of free disk space inside the VHD.
0x20000010
Failed to load the diff package.
0x20000011
Missing rule files.
0x20000021
Corrupt PvD inventory.
0x20000027
T he catalog "MojoControl.dat" is corrupt.
0x2000002B
Corrupt or missing PvD inventory.
0x2000002F
Failed to register user installed MOF on image update, upgrade to 5.6.12 to fix the issue.
0x20000032
Check the PvDactivation.log.txt for the last log entry with a Win32 error code.
0x20
Failed to mount application container for image update, upgrade to 5.6.12 to fix the issue.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.271
Error code
0x70
Descript ion
T here is not enough space on the disk.
St art up f ailed. Cit rix P ersonal vDisk f ailed t o st art [or P ersonal vDisk encount ered an int ernal error]. F or
f urt her assist ance ... St at us code: 20, Error code 0x20000028
T he personal vDisk was found but a PvD session could not be created.
Collect the logs and check SysVol-IvmSupervisor.log for session creation failures:
1. Check for the following log entry " IvmpNativeSessionCreate: failed to create native session, status XXXXX".
2. If the status is 0xc00002cf, fix the problem by adding a new version of the master image to the catalog. T his status
code implies that the USN Journal overflowed due to a large number of changes after an inventory update.
3. Restart the affected virtual desktop. If the problem persists, contact Citrix T echnical Support.
St art up f ailed. Cit rix P ersonal vDisk has been deact ivat ed because an unsaf e syst em shut down was
det ect ed. T o ret ry, select T ry again. If t he problem cont inues, cont act your syst em administ rat or.
T he pooled VM cannot complete its startup with the PvD enabled. First determine why startup cannot be completed.
Possible reasons are that a blue screen appears because:
An incompatible antivirus product is present, for example old versions of T rend Micro, in the master image.
T he user has installed software that is incompatible with PvD. T his is unlikely, but you can check it by adding a new
machine to the catalog and seeing whether it restarts successfully.
T he PvD image is corrupt. T his has been observed in Version 5.6.5.
T o check if the pooled VM is displaying a blue screen, or is restarting prematurely:
Log on to the machine through the hypervisor console.
Click T ry Again and wait for the machine to shut down.
Start the machine through Studio.
Use the hypervisor console to watch the machine console as it starts.
Other troubleshooting:
Collect the memory dump from the machine displaying the blue screen, and send it for further analysis to Citrix
T echnical Support.
Check for errors in the event logs associated with the PvD:
1. Mount UserData.V2.vhd from the root of the P: drive using DiskMgmt.msc by clicking Action > Attach VHD.
2. Launch Eventvwr.msc.
3. Open the system event log (Windows\System32\winevt\logs\system.evtx) from UserData.V2.vhd by clicking Action
> Open saved logs.
4. Open the application event log (Windows\System32\winevt\logs\application.evtx) from UserData.V2.vhd by clicking
Action > Open saved logs.
T he P ersonal vDisk cannot st art . T he P ersonal vDisk could not st art because t he invent ory has not been
updat ed. Updat e t he invent ory in t he mast er image, t hen t ry again. St at us code: 15, Error code: 0x0
T he administrator selected an incorrect snapshot while creating or updating the PvD catalog (that is, the master image
was not shut down using Update Personal vDisk when creating the snapshot).
If Personal vDisk is not enabled, you can view the following events in Windows Event Viewer. Select the Applications node
in the left pane; the Source of the events in the right pane is Citrix Personal vDisk. If Personal vDisk is enabled, none of
these events are displayed.
An Event ID of 1 signifies an information message, an ID of 2 signifies an error. Not all events may be used in every version
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.272
of Personal vDisk.
Event ID
Descript ion
1
Personal vDisk Status: Update Inventory Started.
1
Personal vDisk Status: Update Inventory completed. GUID: %s.
1
Personal vDisk Status: Image Update Started.
1
Personal vDisk Status: Image Update completed.
1
Reset in progress.
1
OK.
2
Personal vDisk Status: Update Inventory Failed with: %s.
2
Personal vDisk Status: Image Update Failed with: %s.
2
Personal vDisk Status: Image Update Failed with Internal Error.
2
Personal vDisk Status: Update Inventory Failed with: Internal Error.
2
Personal vDisk has been disabled because of an improper shutdown.
2
Image update failed. Error code %d.
2
Personal vDisk encountered an internal error. Status code[%d] Error code[0x%X].
2
Personal vDisk reset failed.
2
Unable to find disk for storing user personalization settings.
2
T here is not enough space available on the storage disk to create a Personal vDisk container.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.273
Remove components
Nov 28 , 20 17
To remove components, Citrix recommends using the Windows feature for removing or changing programs. Alternatively,
you can remove components using the command line, or a script on the installation media.
When you remove components, prerequisites are not removed, and firewall settings are not changed. When you remove a
Controller, the SQL Server software and the databases are not removed.
Before removing a Controller, remove it from the Site. Before removing Studio or Director, Citrix recommends closing them.
If you upgraded a Controller from an earlier deployment that included Web Interface, you must remove the Web Interface
component separately; you cannot use the installer to remove Web Interface.
When you remove a VDA, the machine restarts automatically after the removal, by default.
Remove components using the Windows feature for
removing or changing programs
From the Windows feature for removing or changing programs:
T o remove a Controller, Studio, Director, License Server, or StoreFront, select Citrix XenApp <version> or Citrix
XenDesktop <version>, then right-click and select Uninst all. T he installer launches, and you can select the components
to be removed. Alternatively, you can remove StoreFront by right-clicking Cit rix St oreF ront and selecting Uninst all.
T o remove a VDA, select Cit rix Virt ual Delivery Agent <version>, then right-click and select Uninst all. T he installer
launches and you can select the components to be removed.
T o remove the Universal Print Server, select Cit rix Universal P rint Server, then right-click and select Uninst all.
Remove core components using the command line
From the \x64\XenDesktop Setup directory on the installation media, run the XenDeskt opServerSet up.exe command.
T o remove one or more components, use the /remove and /components options.
T o remove all components, use 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 a VDA using the command line
From the \x64\XenDesktop Setup directory on the installation media, run the XenDeskt opVdaSet up.exe command.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.274
T o remove one or more components, use the /remove and /components options.
T o remove all components, use the /removeall option.
For command and parameter details, see Install using the command line.
For example, the following command removes the VDA and Citrix Receiver.
\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /removeall
To remove VDAs using a script in Active Directory; see Install or remove Virtual Delivery Agents using scripts.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.275
Upgrade and migrate
Nov 28 , 20 17
Upgrade
Upgrading changes deployments to the newest component versions without having to set up new machines or Sites; this is
known as an in-place upgrade. You can upgrade to the current version from:
XenDesktop 5.6 *
XenDesktop 7.0
XenDesktop 7.1
XenApp/XenDesktop 7.5
XenApp/XenDesktop 7.6
XenApp/XenDesktop 7.6 LT SR
XenApp/XenDesktop 7.7
XenApp/XenDesktop 7.8
XenApp/XenDesktop 7.9
XenApp/XenDesktop 7.11
XenApp/XenDesktop 7.12
XenApp/XenDesktop 7.13
XenApp/XenDesktop 7.14
XenApp/XenDesktop 7.15 LT SR
To upgrade:
1. Run the installer on the machines where the core components and VDAs are installed. T he software determines if an
upgrade is available and installs the newer version.
2. Use the newly upgraded Studio to upgrade the database and the Site.
* To upgrade from XenDesktop 5.6 to this CR, first upgrade to 7.6 LT SR (with the latest CU), then upgrade to this CR.
For more information, see Upgrade a deployment.
For information about installing Controller hotfixes, see CT X201988.
Migrate
Migrating moves data from an earlier deployment to the newest version. You can migrate a XenApp 6 deployment.
Migrating includes installing current components and creating a new Site, exporting data from the older farm, and then
importing the data to the new Site.
T ip: For information about architecture, component, and feature changes that were introduced with the 7.x releases,
see Changes in 7.x.
To migrate from XenApp 6.5:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.276
1. Install core components and create a new XenApp Site.
2. From the XenApp 6.5 controller, use PowerShell cmdlets to export policy and/or farm data to XML files. You can edit the
XML file content to tailor the information you will import.
3. From the new Site, use PowerShell cmdlets and the XML files to import policy and/or application data to the new Site.
4. Complete post-migration tasks on the new Site.
For more information, see Migrate XenApp 6.x.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.277
Changes in 7.x
Jan 0 3, 20 18
XenApp and XenDesktop architecture, terminology, and features changed, beginning with the 7.x releases. If you are
familiar with only earlier (pre-7.x) versions, this article can acquaint you with the changes.
T ip: After you have moved to a 7.x version, changes to later versions are listed in What's new.
Unless specifically noted, 7.x refers to XenApp version 7.5 or later, and XenDesktop version 7 or later.
T his article provides an overview. For comprehensive information about moving from pre-7.x to the latest version, see
Upgrade to XenApp 7.
Element differences between XenApp 6 and the
current XenApp version
Although they are not exact equivalents, the following table helps map functional elements from XenApp 6.5 and previous
versions to XenApp and XenDesktop versions, beginning with 7.x. Descriptions of architectural differences follow.
Instead of this in XenApp < 6.5:
T hink of this, in XenApp and XenDesktop > 7.x:
Independent Management Architecture (IMA)
FlexCast Management Architecture (FMA)
Farm
Site
Worker Group
Machine Catalog
Delivery Group
Worker
Virtual Delivery Agent (VDA)
Server OS machine, Server OS VDA
Desktop OS machine, Desktop OS VDA
Remote Desktop Services (RDS) or Terminal Services
Server OS machine, Server OS VDA
machine
Zone and Data Collector
Delivery Controller
Delivery Services Console
Citrix Studio and Citrix Director
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.278
Publishing applications
Delivering applications
Data store
Database
Load Evaluator
Load Management Policy
Administrator
Delegated Administrator
Role
Scope
Architecture differences
Beginning with 7.x versions, XenApp and XenDesktop are based on FlexCast Management Architecture (FMA). FMA is a
service-oriented architecture that allows interoperability and management modularity across Citrix technologies. FMA
provides a platform for application delivery, mobility, services, flexible provisioning, and cloud management.
FMA replaces the Independent Management Architecture (IMA) used in XenApp 6.5 and previous versions.
T hese are the key elements of FMA in terms of how they relate to elements of XenApp 6.5 and previous versions:
Delivery Sit es : Farms were the top-level objects in XenApp 6.5 and previous versions. In XenApp 7.x and XenDesktop 7.x,
the Site is the highest level item. Sites offer applications and desktops to groups of users. FMA requires that you must
be in a domain to deploy a Site. For example, to install the servers, your account must have local administrator privileges
and be a domain user in the Active Directory.
Machine Cat alogs and Delivery Groups : Machines hosting applications in XenApp 6.5 and previous versions belonged
to Worker Groups for efficient management of the applications and server software. Administrators could manage all
machines in a Worker Group as a single unit for their application management and load-balancing needs. Folders were
used to organize applications and machines. In XenApp 7.x and XenDesktop 7.x, you use a combination of Machine
Catalogs, Delivery Groups, and Application Groups to manage machines, load balancing, and hosted applications or
desktops. You can also use application folders.
VDAs : In XenApp 6.5 and previous versions, worker machines in Worker Groups ran applications for the user and
communicated with data collectors. In XenApp 7.x and XenDesktop 7.x, the VDA communicates with Delivery Controllers
that manage the user connections.
Delivery Cont rollers: In XenApp 6.5 and previous versions there was a zone master responsible for user connection
requests and communication with hypervisors. In XenApp 7.x and XenDesktop 7.x, Controllers in the Site distribute and
handle connection requests. In XenApp 6.5 and previous versions, zones provided a way to aggregate servers and
replicate data across WAN connections. Although zones have no exact equivalent in XenApp 7.x and XenDesktop 7.x,
the 7.x zones and zone preference functionality enables you to help users in remote regions connect to resources
without necessarily forcing their connections to traverse large segments of a WAN.
St udio and Direct or: Use the Studio console to configure your environments and provide users with access to
applications and desktops. Studio replaces the Delivery Services Console in XenApp 6.5 and previous versions.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.279
Administrators use Director to monitor the environment, shadow user devices, and troubleshoot IT issues. T o shadow
users, Windows Remote Assistance must be enabled; it is enabled by default when the VDA is installed.
Delivering applicat ions : XenApp 6.5 and previous versions used the Publish Application wizard to prepare applications
and deliver them to users. In XenApp 7.x and XenDesktop 7.x, you use Studio to create and add applications to make
them available to users who are included in a Delivery Group and optionally, Application Groups. Using Studio, you first
configure a Site, create and specify Machine Catalogs, and then create Delivery Groups that use machines from those
catalogs. T he Delivery Groups determine which users have access to the applications you deliver. You can optionally
choose to create Application Groups as an alternative to multiple Delivery Groups.
Dat abase : XenApp 7.x and XenDesktop 7.x do not use the IMA data store for configuration information. T hey use a
Microsoft SQL Server database to store configuration and session information.
Load Management P olicy : In XenApp 6.5 and previous versions, load evaluators use predefined measurements to
determine the load on a machine. User connections can be matched to the machines with a lower load. In XenApp 7.x
and XenDesktop 7.x, use load management policies for balancing loads across machines.
Delegat ed Administ rat ion : In XenApp 6.5 and previous versions, you created custom administrators and assigned them
permissions based on folders and objects. In XenApp 7.x and XenDesktop 7.x, custom administrators are based on role
and scope pairs. A role represents a job function and has defined permissions associated with it to allow delegation. A
scope represents a collection of objects. Built-in administrator roles have specific permissions sets, such as help desk,
applications, hosting, and catalog. For example, help desk administrators can work only with individual users on specified
sites, while full administrators can monitor the entire deployment and resolve system-wide IT issues.
Feature comparison
T he transition to FMA also means some features available in XenApp 6.5 and previous versions may be implemented
differently or may require you to substitute other features, components, or tools to achieve the same goals.
Inst ead of t his in XenApp 6.5 and
bef ore:
Use t his, beginning wit h XenApp and XenDeskt op 7 .x:
Session prelaunch and session linger
Session prelaunch and session linger configured by editing Delivery Group
configured with policy settings
settings.
As in XenApp 6.5, these features help users connect to applications quickly,
by starting sessions before they are requested (session prelaunch) and
keeping sessions active after a user closes all applications (session linger). In
XenApp and XenDesktop 7.x, you enable these features for specified users
by configuring these settings for existing Delivery groups. See Configure
session prelaunch and session linger.
Support for unauthenticated
Support for unauthenticated (anonymous) users is provided by configuring
(anonymous) users provided by granting
this option when setting user properties of a Delivery Group. See Users.
rights to anonymous user when setting
the properties of published applications
Local host cache permits a worker
https://docs.citrix.com
Local Host Cache allows connection brokering operations to continue when
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.280
servers to function even when a
the connection between a Controller and the Site database fails. T his
connection to the data store is not
implementation is more robust and requires less maintenance. See Local Host
available
Cache.
As an alternative to using Local Host Cache, connection leasing enables users
to connect and reconnect to their most recently used applications and
desktops, even when the Site database is not available. See Connection
leasing.
Application streaming
Citrix App-V delivers streamed applications, which are managed using Studio.
Web Interface
Citrix recommends you transition to StoreFront.
SmartAuditor to record on-screen
Beginning with 7.6 Feature Pack 1, this functionality is provided by Session
activity of a user's session.
Recording. You can also use Configuration Logging to log all session activities
from an administrative perspective.
Power and Capacity Management to
Use the Microsoft Configuration Manager.
help reduce power consumption and
manage server capacity
Feature support and changes
T he following features are not currently provided, no longer supported, or have changed significantly in XenApp or
XenDesktop, beginning with 7.x versions.
Secure ICA encrypt ion below 128-bit : In releases earlier than 7.x, Secure ICA could encrypt client connections for basic,
40-bit, 56-bit, and 128-bit encryption. In 7.x releases, Secure ICA encryption is available only for 128-bit encryption.
Legacy print ing : T he following printing features are not supported in 7.x releases:
Backward compatibility for DOS clients and 16-bit printers.
Support for printers connected to Windows 95 and Windows NT operating systems, including enhanced extended
printer properties and Win32FavorRetainedSetting.
Ability to enable or disable auto-retained and auto-restored printers.
DefaultPrnFlag, a registry setting for servers that is used to enable or disable auto-retained and auto-restored printers,
which store in user profiles on the server.
NOT E: Legacy client printer names are supported.
Secure Gat eway : In releases earlier than 7.x, Secure Gateway was an option to provide secure connections between the
server and user devices. NetScaler Gateway is the replacement option for securing external connections.
Shadowing users : In releases earlier than 7.x, administrators set policies to control user-to-user shadowing. In 7.x releases,
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.281
shadowing end-users is an integrated feature of the Director component, which uses Windows Remote Assistance to
allow administrators to shadow and troubleshoot issues for delivered seamless applications and virtual desktops.
F lash v1 Redirect ion: Clients that do not support second generation Flash Redirection (including Citrix Receiver for
Windows earlier than 3.0, Citrix Receiver for Linux earlier than 11.100, and Citrix Online Plug-in 12.1) will fall back to serverside rendering for legacy Flash Redirection features. VDAs included with 7.x releases support second generation Flash
Redirection features.
Local Text Echo: T his feature was used with earlier Windows application technologies to accelerate the display of input
text on user devices on high latency connections. It is not included in 7.x releases due to improvements to the graphics
subsystem and HDX SuperCodec.
Single Sign-on: T his feature, which provides password security, is not supported for Windows 8, Windows Server 2012, and
newer supported Windows operating systems versions. It is still supported for Windows 2008 R2 and Windows 7
environments, but is not included with 7.x releases. You can locate it on the Citrix download website:
http://citrix.com/downloads.
Oracle dat abase support : 7.x releases require a SQL Server database.
Healt h Monit oring and Recovery (HMR): In releases earlier than 7.x, HMR could run tests on the servers in a server farm
to monitor their state and discover any health risks. In 7.x releases, Director offers a centralized view of system health by
presenting monitoring and alerting for the entire infrastructure from within the Director console.
Cust om ICA files: Custom ICA files were used to enable direct connection from user devices (with the ICA file) to a specific
machine. In 7.x releases, this feature is disabled by default, but can be enabled for normal usage using a local group or can
be used in high-availability mode if the Controller becomes unavailable.
Management Pack f or Syst em Cent er Operat ions Manager (SCOM) 2007 : T he management pack, which
monitored the activity of XenApp farms using SCOM, does not support 7.x releases. See the current Citrix SCOM
Management Pack for XenApp and XenDesktop.
CNAME f unct ion: T he CNAME function was enabled by default in releases earlier than 7.x. Deployments depending on
CNAME records for FQDN rerouting and the use of NET BIOS names might fail. In 7.x releases, the Delivery Controller autoupdate feature dynamically updates the list of Controllers and automatically notifies VDAs when Controllers are added to
and removed from the Site. T he Controller auto-update feature is enabled by default in Citrix policies, but can be disabled.
Alternatively, you can re-enable the CNAME function in the registry to continue with your existing deployment and allow
FQDN rerouting and the use of NET BIOS names. For more information, see CT X137960.
Quick Deploy wizard: In XenDesktop releases earlier than 7.x, this Studio option allowed a fast deployment of a fully
installed XenDesktop deployment. T he new simplified installation and configuration workflow in 7.x releases eliminates the
need for the Quick Deploy wizard option.
Remot e P C Service configurat ion file and P owerShell script f or aut omat ic administ rat ion : Remote PC Access is
now integrated into Studio and the Controller.
Workflow St udio: In releases earlier than 7.x, Workflow Studio was the graphical interface for workflow composition for
XenDesktop. T he feature is not supported in 7.x releases.
Launching of non-published programs during client connect ion: In releases earlier than 7.x, this Citrix policy setting
specified whether to launch initial applications or published applications through ICA or RDP on the server. In 7.x releases,
this setting specifies only whether to launch initial applications or published applications through RDP on the server.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.282
Deskt op launches: In releases earlier than 7.x, this Citrix policy setting specified whether non-administrative users can
connect to a desktop session. In 7.x releases, non-administrative users must be in a VDA machine's Direct Access Users
group to connect to sessions on that VDA. T he Desktop launches setting enables non-administrative users in a VDA's
Direct Access Users group to connect to the VDA using an ICA connection. T he Desktop launches setting has no effect on
RDP connections; users an VDA's Direct Access Users group can connect to the VDA using an RDP connection whether or
not this setting is enabled.
Color dept h: In Studio releases earlier than 7.6, you specified color depth in a Delivery Group's User Settings. Beginning in
version 7.6, color depth for the Delivery Group can be set using the New-BrokerDesktopGroup or Set-BrokerDesktopGroup
PowerShell cmdlet.
Launch t ouch-opt imized deskt op: T his setting is disabled and not available for Windows 10 and Windows Server 2016
machines. For more information, see Mobile experience policy settings.
COM P ort Mapping: COM Port Mapping allowed or prevented access to COM ports on the user device. COM Port
Mapping was previously enabled by default. In 7.x releases of XenDesktop and XenApp, COM Port Mapping is disabled by
default. For details, see Configure COM Port and LPT Port Redirection settings using the registry.
LP T P ort Mapping: LPT Port Mapping controls the access of legacy applications to LPT ports. LPT Port Mapping was
previously enabled by default. In 7.x releases, LPT Port Mapping is disabled by default.
P CM Audio Codec: Only HT ML5 clients support the PCM Audio Codec in 7.x releases.
Support f or Microsof t Act iveSync .
P roxy support f or older versions: T his includes:
Microsoft Internet Security and Acceleration (ISA) 2006 (Windows Server 2003)
Oracle iPlanet Proxy Server 4.0.14 (Windows Server 2003)
Squid Proxy Server 3.1.14 (Ubuntu Linux Server 11.10)
For more information, see the Citrix Receiver documentation for your version.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.283
Upgrade a deployment
Nov 28 , 20 17
In this article:
Introduction
Upgrade sequence
Which product component versions can be upgraded
Preparation and limitations
Mixed environment considerations
VDAs on Windows XP or Windows Vista
VDAs on Windows 7, Windows 8.x, early Wndows 10, Windows Server 2008 R2, and Windows Server 2012
Mixed VDA support
Upgrade procedure
Upgrade the databases and the Site
Introduction
You can upgrade certain deployments to newer versions without having to first set up new machines or Sites. T hat process
is called an in-place upgrade. See Upgrade for a list of the versions you can upgrade.
To start an upgrade, you run the installer from the new version to upgrade previously installed core components (Delivery
Controller, Citrix Studio, Citrix Director, Citrix License Server) and VDAs. T hen you upgrade the databases and the Site.
If you attempt to install (or upgrade to) a Windows VDA on an OS that is not supported for this XenApp and XenDesktop
version, a message guides you to a CT X article that describes your options.
Be sure to review all the information in this article before beginning the upgrade.
Upgrade sequence
T he following diagram summarizes the upgrade sequence. Details are provided in Upgrade procedure below. For example, if
you have more than one core component installed on a server, running the installer on that machine will upgrade all
components that have new versions. You might want to upgrade the VDA used in a master image, and then update the
image. T hen, update the catalog that uses that image and the Delivery Group that uses that catalog. Details also cover
how to upgrade the Site databases and the Site automatically or manually.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.284
Which product component versions can be upgraded
Using the product installer, you can upgrade:
Citrix License Server, Studio, and StoreFront
Delivery Controllers 5.6 or later
VDA 5.6 or later
Check System requirements to ensure that the OS is upported for the new VDA.
You must use the product installer to upgrade a VDA; you cannot use an MSI.
If the installer detects Receiver for Windows (Receiver.exe) on the machine, it is upgraded to the Receiver version
included on the product installation media.
VDA 5.6 through VDA 7.8: If the installer detects Receiver for Windows Enterprise (CitrixReceiverEnterprise.exe) on the
machine, it is upgraded to Receiver for Windows Enterprise 3.4.
Director 1 or later
Database: T his Studio action upgrades the schema and migrates data for the Site database (plus the Configuration
Logging and Monitoring databases, if you're upgrading from an earlier 7.x version)
Personal vDisk
Using the guidance in the feature/product documentation, upgrade the following if needed:
Provisioning Services (for XenApp 7.x and XenDesktop 7.x, Citrix recommends using the latest released version; the
minimum supported version is Provisioning Services 7.0).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.285
Upgrade the Provisioning Services server using the server rolling upgrade, and the clients using vDisk versioning.
Provisioning Services 7.x does not support creating new desktops with XenDesktop 5 versions. So, although existing
desktops will continue to work, you cannot use Provisioning Services 7.x to create new desktops until you upgrade
XenDesktop. T herefore, if you plan a mixed environment of XenDesktop 5.6 and 7.x Sites, do not upgrade Provisioning
Services to version 7.
Host hypervisor version.
StoreFront.
Profile Management.
Limitations
T he following limitations apply to upgrades:
Select ive component inst all
If you install or upgrade any components to the new version but choose not to upgrade other components (on
different machines) that require upgrade, Studio will remind you. For example, let's say an upgrade includes new
versions of the Controller and Studio. You upgrade the Controller but you do not run the installer on the machine
where Studio is installed. Studio will not let you continue to manage the Site until you upgrade Studio.
You do not have to upgrade VDAs, but Citrix recommends upgrading all VDAs to enable you to use all available
features.
XenApp version earlier t han 7 .5
You cannot upgrade from a XenApp version earlier than 7.5. You can migrate from XenApp 6.x; see Migrate XenApp
6.x.
XenDeskt op version earlier t han 5.6
You cannot upgrade from a XenDesktop version earlier than 5.6.
XenDeskt op Express Edit ion
You cannot upgrade XenDesktop Express edition. Obtain and install a license for a currently supported edition, and
then upgrade it.
Early Release or Technology P review versions
You cannot upgrade from a XenApp or XenDesktop Early Release or Technology Preview version.
Windows XP /Vist a
You cannot install current VDAs on operating systems that are no longer supported by Microsoft or Citrix, such as
Windows XP or Windows Vista.
Ot her earlier OSs
If you have VDAs installed on machines after Windows XP/Vista, but earlier than recent Windows 10 or Windows
Server 2012 R2, see the ection below on VDAs on Windows 7, Windows 8.x, early Windows 10, Windows Server 2008
R2, and Windows Server 2012.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.286
P roduct select ion
When you upgrade from an earlier 7.x version, you do not choose or specify the product (XenApp or XenDesktop)
that was set during the initial installation.
Mixed environment s/sit es
If you must continue to run earlier version Sites and current version Sites, see Mixed environment considerations.
Preparation
Before beginning an upgrade:
Decide which inst aller and int erf ace t o use
Use the full-product installer from the XenApp or XenDesktop ISO to upgrade core components. You can upgrade
VDAs using the full-product installer or one of the standalone VDA installers. All installers offer graphical and
command line interfaces. For more information, see Installers.
You cannot upgrade by importing or migrating data from a version that can be upgraded. (Note: Some much earlier
versions must be migrated instead of upgraded; see Upgrade and migrate for a list of which versions can be upgraded.)
If you originally installed a desktop VDA with the VDAWorkstationCoreSetup.exe installer, Citrix recommends using
that installer to upgrade it. If you use the full-product VDA installer or the VDAWorkstationSetup.exe installer to
upgrade the VDA, the components that were originally excluded might be be installed, unless you expressly
omit/exclude them from the upgrade.
For example, if you installed a version 7.14 VDA using VDAWorkstationCoreSetup.exe, and then used the full-product
installer to upgrade that VDA to version 7.16, the components that were excluded from the original installation (such
as Profile management) might be installed during the upgrade, if you accept the default settings or do not use the
/exclude command-line option.
Check your Sit e's healt h
Ensure the Site is in a stable and functional state before starting an upgrade. If a Site has issues, upgrading will not fix
them, and can leave the Site in a complex state that is difficult to recover from. To test the Site, select the Sit e entry
in the Studio navigation pane. In the Site configuration portion of the middle pane, click Test sit e .
Back up t he Sit e, monit oring, and Configurat ion Logging dat abases
Follow the instructions in CT X135207. If any issues are discovered after the upgrade, you can restore the backup.
Optionally, back up templates and upgrade hypervisors, if needed.
Complete any other preparation tasks dictated by your business continuity plan.
Ensure your Cit rix licensing is up t o dat e
Before upgrading, be sure your Customer Success Services / Software Maintenance / Subscription Advantage date is
valid for the new product version. If you are upgrading from an earlier 7.x product version, the date must be at least
2017.1115.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.287
Close applicat ions and consoles
Before starting an upgrade, close all programs that might potentially cause file locks, including administration consoles
and PowerShell sessions. (Restarting the machine ensures that any file locks are cleared, and that there are no
Windows updates pending.)
Import ant : Before starting an upgrade, stop and disable any third-party monitoring agent services.
Ensure you have proper permissions
In addition to being a domain user, you must be a local administrator on the machines where you are upgrading
product components.
T he Site database and the Site can be upgraded automatically or manually. For an automatic database upgrade, the
Studio user's permissions must include the ability to update the SQL Server database schema (for example, the
db_securityadmin or db_owner database role). For details, see the Databases article. If the Studio user does not have
those permissions, initiating a manual database upgrade will generate scripts. T he Studio user runs some of the scripts
from Studio; the database administrator runs other scripts using a tool such as SQL Server Management Studio.
Mixed environment considerations
When your environment contains Sites/farms with different product versions (a mixed environment), Citrix recommends
using StoreFront to aggregate applications and desktops from different product versions (for example, if you have a
XenDesktop 7.14 Site and a XenDesktop 7.16 Site). For details, see the StoreFront documentation.
In a mixed environment, continue using the Studio and Director versions for each release, but ensure that different
versions are installed on separate machines.
If you plan to run XenDesktop 5.6 and 7.x Sites simultaneously and use Provisioning Services for both, either deploy a
new Provisioning Services for use with the 7.x Site, or upgrade the current Provisioning Services and be unable to
provision new workloads in the XenDesktop 5.6 Site.
Within each Site, Citrix recommends upgrading all components. Although you can use earlier versions of some components,
all the features in the latest version might not be available. For example, although you can use current VDAs in deployments
containing earlier Controller versions, new features in the current release may not be available. VDA registration issues can
also occur when using non-current versions.
Sites with Controllers at version 5.x and VDAs at version 7.x should remain in that state only temporarily. Ideally, you
should complete the upgrade of all components as soon as possible.
Do not upgrade a standalone Studio version until you are ready to use the new version.
VDAs on Windows 7, Windows 8.x, early Windows 10,
Windows Server 2008 R2, and Windows Server 2012
You cannot upgrade VDAs installed on machines running Windows 7, Windows 8.x, Windows 10 (version 1507 and 1511),
Windows Server 2008 R2, and Windows Server 2012 to this XenApp and XenDesktop version. If you attempt to install or
upgrade a VDA on one of those machines to the current version, a message guides you to CT X139030.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.288
For machines with any of these OSs, you have several options.
Reimage the machine to a supported Windows version, and then install the new VDA.
If reimaging the machine is not an option but you want to upgrade the OS, uninstall the VDA before upgrading the OS.
Otherwise, the VDA will be in an unsupported state. T hen, install the new VDA.
If you want to continue to use machines with an OS that is no longer supported for the current VDA (noted above),
XenApp and XenDesktop 7.15 LT SR is the most current supported VDA version. You can use 7.15 LT SR VDAs in a
deployment with core components that you've upgraded to newer versions (such as Delivery Controllers).
If the machine already has a 7.15 LT SR VDA installed (and you attempt to install a newer VDA), a message informs you
that you're using the latest supported version.
If the machine already has a VDA earlier than 7.15 LT SR installed, a message guides you to CT X139030 for
information. You can download 7.15 LT SR VDAs from the Citrix web site.
Mixed VDA support
When you upgrade the product to a later version, Citrix recommends you upgrade all the core components and VDAs so
you can access all the new and enhanced features in your edition.
In some environments, you may not be able to upgrade all VDAs to the most current version. In this scenario, when you
create a machine catalog, you can specify the VDA version installed on the machines. By default, this setting specifies the
latest recommended VDA version; you need to consider changing this setting only if the machine catalog contains
machines with earlier VDA versions. However, mixing VDA versions in a machine catalog is not recommended.
If a machine catalog is created with the default recommended VDA version setting, and any of the machines in the catalog
has an earlier VDA version installed, those machines will not be able to register with the Controller and will not work.
For more information, see VDA versions and functional levels.
Upgrade procedure
To run the product installer graphical interface, log on to the machine and then insert the media or mount the ISO drive for
the new release. Double-click Aut oSelect . To use the command-line interface, see Install using the command line.
St ep 1. If more than one core component is installed on the same server (for example, the Controller, Studio, and License
Server) and several of those components have new versions available, they will all be upgraded when you run the installer on
that server.
If any core components are installed on machines other than the Controller, run the installer on each of those machines.
T he recommended order is: License Server, StoreFront, and then Director.
St ep 2. If you use Provisioning Services, upgrade the PVS servers and target devices, using the guidance in the Provisioning
Services documentation.
St ep 3. Run the product installer on machines containing VDAs. (See Step 12 if you use master images and Machine
Creation Services.)
St ep 4 . Run the product installer on half of the Controllers. (T his also upgrades any other core components installed on
those servers.) For example, if your Site has four Controllers, run the installer on two of them.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.289
Leaving half of the Controllers active allows users to access the Site. VDAs can register with the remaining Controllers.
T here may be times when the Site has reduced capacity because fewer Controllers are available. T he upgrade causes
only a brief interruption in establishing new client connections during the final database upgrade steps. T he upgraded
Controllers cannot process requests until the entire Site is upgraded.
If your Site has only one Controller, the Site is inoperable during the upgrade.
St ep 5. If Studio is installed on a different machine than one you've already upgraded, run the installer on the machine
where Studio is installed.
St ep 6. From the newly upgraded Studio, upgrade the Site database. For details, see Upgrade the databases and the Site.
St ep 7 . From the newly upgraded Studio, select Cit rix St udio site-name in the navigation pane. Select the Common
T asks tab. Select Upgrade remaining Delivery Cont rollers .
St ep 8. After completing the upgrade and confirming completion, close and then reopen Studio. Studio might prompt for
an additional Site upgrade to register the Controller’s services to the Site, or to create a zone ID if it does not yet exist.
St ep 9. In the Site Configuration section of the Common Tasks page, select P erf orm regist rat ion . Registering the
Controllers makes them available to the Site.
St ep 10. After you select F inish when the upgrade completes, you are offered the opportunity to enroll in the Citrix
telemetry programs, which collect information about your deployment. T hat information is used to improve product quality,
reliability, and performance.
St ep 11. After upgrading components, the database, and the Site, test the newly-upgraded Site. From Studio, select Cit rix
St udio site-name in the navigation pane. Select the Common T asks tab and then select Test Sit e . T hese tests were run
automatically after you upgraded the database, but you can run them again at any time.
T he Test Site functionality might fail for a Controller installed on Windows Server 2016, when a local SQL Server
Express is used for the Site database, if the SQL Server Browser service is not started. To avoid this, complete the
following tasks.
1. Enable the SQL Server Browser service (if required) and then start it.
2. Restart the SQL Server (SQLEXPRESS) service.
St ep 12. If you use Machine Creation Services and want to use upgraded VDAs: After you upgrade and test the
deployment, update the VDA used in the master images (if you haven't done that already). Update master images that use
those VDAs. See Update or create a new master image. T hen update machine catalogs that use those master images, and
upgrade Delivery Groups that use those catalogs.
After upgrading the core components and VDAs, use the newly upgraded Studio to initiate an automatic or manual
database and Site upgrade.
Remember: Check the Preparation section above for permission requirements.
For an automatic database upgrade, the Studio user's permissions must include the ability to update the SQL Server
database schema.
For a manual upgrade, the Studio user runs some of the generated scripts from Studio. T he database administrator runs
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.290
other scripts, using either the SQLCMD utility or the SQL Server Management Studio in SQLCMD mode. Otherwise,
inaccurate errors can result.
Import ant : Citrix strongly recommends that you back up the database before upgrading. See CT X135207.
During a database upgrade, product services are disabled. During that time, Controllers cannot broker new connections for
the Site, so plan carefully.
After the database upgrade completes and product services are enabled, Studio tests the environment and configuration,
and then generates an HT ML report. If problems are identified, you can restore the database backup. After resolving issues,
you can upgrade the database again.
Upgrade t he dat abase and Sit e aut omat ically:
Launch the newly upgraded Studio. After you choose to start the Site upgrade automatically and confirm that you are
ready, the database and Site upgrade proceeds.
Upgrade t he dat abase and Sit e manually:
St ep 1. Launch the newly-upgraded Studio. After you choose to manually upgrade the Site, the wizard checks for License
Server compatibility and requests confirmation. After you confirm that you have backed up the database, the wizard
generates and displays the scripts and a checklist of upgrade steps.
St ep 2. Run the following scripts in the order shown.
Script
Descript ion
DisableServices.ps1
PowerShell script to be run by the Studio user on a Controller to disable product
services.
UpgradeSiteDatabase.sql
SQL script to be run by the database administrator on the server containing the
Site database.
UpgradeMonitorDatabase.sql
SQL script to be run by the database administrator on the server containing the
Monitor database.
UpgradeLoggingDatabase.sql
SQL script to be run by the database administrator on the server containing the
Configuration Logging database. Run this script only if this database changes (for
example, after applying a hotfix).
EnableServices.ps1
PowerShell script to be run by the Studio user on a Controller to enable product
services.
St ep 3. After completing the checklist tasks. click F inish upgrade .
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.291
Upgrade a XenApp 6.5 worker to a new VDA
Nov 28 , 20 17
After you migrate a XenApp 6.5 farm, you can use your XenApp 6.5 servers that were configured in session-host only mode
(also called session-only or worker servers) by removing the earlier software, upgrading the OS, and then installing a new
VDA for Server OS.
NOT E: Although you can upgrade a XenApp 6.5 worker server, installing the current VDA software on a clean machine
provides better security.
To upgrade a XenApp 6.5 worker to a new VDA:
1. Remove Hotfix Rollup Pack 7 for XenApp 6.5, using the instructions in the hotfix readme. See CT X202095.
2. Uninstall XenApp 6.5, using the instructions in Removing Roles and Components. T his process requires several restarts. If
an error occurs during the uninstallation, check the uninstall error log referenced in the error message. T hat log file
resides in the folder "%T EMP%\Citrix\XenDesktop Installation\XenApp 6.5 Uninstall Log Files\."
3. Upgrade the server's operating system to a supported version. See the VDA for Server OS section in System
requirements. for a list of supported platforms
4. Install a VDA for Server OS, using an installer provided with this release. See Install VDAs or Install using the command
line.
After you install the new VDA, from Studio in the new XenApp Site, create machine catalogs (or edit existing catalogs) for
the upgraded workers
T roubleshoot ing
Symptoms: Removal of the XenApp 6.5 software fails. T he uninstall log contains the message: "Error 25703. An error
occurred while plugging XML into Internet Information Server. Setup cannot copy files to your IIS Scripts directory. Please
make sure that your IIS installation is correct."
Cause: T he issue occurs on systems where (1) during the initial XenApp 6.5 installation, you indicated that the Citrix XML
Service (CtxHttp.exe) should not share a port with IIS, and (2) .NET Framework 3.5.1 is installed.
Resolution:
1. Remove the Web Server (IIS) role using the Windows Remove Server Roles wizard. (You can reinstall the Web Server (IIS)
role later.)
2. Restart the server.
3. Using Add/Remove Programs, uninstall Citrix XenApp 6.5 and Microsoft Visual C++ 2005 Redistributable (x64), version
8.0.56336.
4. Restart the server.
5. Install the VDA for Windows Server OS.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.292
Migrate XenApp 6.x
Nov 28 , 20 17
NOT E: You cannot use the Citrix Smart Migrate product with this version of XenApp and XenDesktop. However, the Migration Tool is available.
XenApp 6.x Migration Tool
T he XenApp 6.x Migration Tool is a collection of PowerShell scripts containing cmdlets that migrate XenApp 6.x (6.0 or 6.5) policy and farm data. On the
XenApp 6.x controller server, you run export cmdlets that gather that data into XML files. T hen, from the XenApp 7.6 Controller, you run import cmdlets
that create objects using the data gathered during the export.
A video overview of the migration tool is available here.
T he following sequence summarizes the migration process; details are provided later.
1. On a XenApp 6.0 or 6.5 controller:
1. Import the PowerShell export modules.
2. Run the export cmdlets to export policy and/or farm data to XML files.
2. Copy the XML files (and icons folder if you chose not to embed them in the XML files during the export) to the XenApp 7.6 Controller.
3. On the XenApp 7.6 Controller:
1. Import the PowerShell import modules.
2. Run the import cmdlets to import policy and/or farm data (applications), using the XML files as input.
4. Complete post-migration steps.
Before you run an actual migration, you can export your XenApp 6.x settings and then perform a preview import on the XenApp 7.6 site. T he preview
identifies possible failure points so you can resolve issues before running the actual import. For example, a preview might detect that an application with
the same name already exists in the new XenApp 7.6 site. You can also use the log files generated from the preview as a migration guide.
Unless otherwise noted, the term 6.x refers to XenApp 6.0 or 6.5.
T his December 2014 release (version 20141125) contains the following updates:
If you encounter issues using the migration tool on a XenApp 6.x farm, report them to the support forum http://discussions.citrix.com/forum/1411xenapp-7x/, so that Citrix can investigate them for potential improvements to the tool.
New packaging - the XAMigration.zip file now contains two separate, independent packages: ReadIMA.zip and ImportFMA.zip. T o export from a
XenApp 6.x server, you need only ReadIMA.zip. T o import to a XenApp 7.6 server, you need only ImportFMA.zip.
T he Export-XAFarm cmdlet supports a new parameter (EmbedIconData) that eliminates the need to copy icon data to separate files.
T he Import-XAFarm cmdlet supports three new parameters:
MatchServer - import applications from servers whose names match an expression
NotMatchServer - import applications from servers whose names do not match an expression
IncludeDisabledApps - import disabled applications
Prelaunched applications are not imported.
T he Export-Policy cmdlet works on XenDesktop 7.x.
T he migration tool is available under the XenApp 7.6 Citrix download site. T he XAMigration.zip file contains two separate, independent packages:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.293
ReadIMA.zip - contains the files used to export data from your XenApp 6.x farm, plus shared modules.
Module or f ile
Descript ion
ExportPolicy.psm1
PowerShell script module for exporting XenApp 6.x policies to an XML file.
ExportXAFarm.psm1
PowerShell script module for exporting XenApp 6.x farm settings to an XML file.
ExportPolicy.psd1
PowerShell manifest file for script module ExportPolicy.psm1.
ExportXAFarm.psd1
PowerShell manifest file for script module ExportXAFarm.psm1.
LogUtilities.psm1
Shared PowerShell script module that contains logging functions.
XmlUtilities.psd1
PowerShell manifest file for script module XmlUtilities.psm1.
XmlUtilities.psm1
Shared PowerShell script module that contains XML functions.
ImportFMA.zip - contains the files used to import data to your XenApp 7.6 farm, plus shared modules.
Module or f ile
Descript ion
ImportPolicy.psm1
PowerShell script module for importing policies to XenApp 7.6.
ImportXAFarm.psm1
PowerShell script module for importing applications to XenApp 7.6
ImportPolicy.psd1
PowerShell manifest file for script module ImportPolicy.psm1.
ImportXAFarm.psd1
PowerShell manifest file for script module ImportXAFarm.psm1.
PolicyData.xsd
XML schema for policy data.
XAFarmData.xsd
XML schema for XenApp farm data.
LogUtilities.psm1
Shared PowerShell script module that contains logging functions.
XmlUtilities.psd1
PowerShell manifest file for script module XmlUtilities.psm1.
XmlUtilities.psm1
Shared PowerShell script module that contains XML functions.
Not all policies settings are imported; see Policy settings not imported. Settings that are not supported are ignored and noted in the log file.
While all application details are collected in the output XML file during the export operation, only server-installed applications are imported into the
XenApp 7.6 site. Published desktops, content, and most streamed applications are not supported (see the Import-XAFarm cmdlet parameters in Stepby-step: import data for exceptions).
Application servers are not imported.
Many application properties are not imported because of differences between the XenApp 6.x Independent Management Architecture (IMA) and the
XenApp 7.6 FlexCast Management Architecture (FMA) technologies; see Application property mapping.
A Delivery Group is created during the import. See Advanced use for details about using parameters to filter what is imported.
Only Citrix policy settings created with the AppCenter management console are imported; Citrix policy settings created with Windows Group Policy
Objects (GPOs) are not imported.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.294
T he migration scripts are intended for migrations from XenApp 6.x to XenApp 7.6 only.
Nested folders greater than five levels deep are not supported by Studio and will not be imported. If your application folder structure includes folders
more than five levels deep, consider reducing the number of nested folder levels before importing.
T he XML files created by the export scripts can contain sensitive information about your environment and organization, such as user names, server
names, and other XenApp farm, application, and policy configuration data. Store and handle these files in secure environments.
Carefully review the XML files before using them as input when importing policies and applications, to ensure they contain no unauthorized
modifications.
Policy object assignments (previously known as policy filters) control how policies are applied. After importing the policies, carefully review the object
assignments for each policy to ensure that there are no security vulnerabilities resulting from the import. Different sets of users, IP addresses, or client
names may be applied to the policy after the import. T he allow/deny settings may have different meanings after the import.
T he scripts provide extensive logging that tracks all cmdlet executions, informative messages, cmdlet execution results, warnings, and errors.
Most Citrix PowerShell cmdlet use is logged. All PowerShell cmdlets in the import scripts that create new site objects are logged.
Script execution progress is logged, including the objects being processed.
Major actions that affect the state of the flow are logged, including flows directed from the command line.
All messages printed to the console are logged, including warnings and errors.
Each line is time-stamped to the millisecond.
Citrix recommends specifying a log file when you run each of the export and import cmdlets.
If you do not specify a log file name, the log file is stored in the current user's home folder (specified in the PowerShell $HOME variable) if that folder
exists; otherwise, it is placed in the script's current execution folder. T he default log name is "XFarmYYYYMMDDHHmmSS-xxxxxx" where the last six
digits constitute a random number.
By default, all progress information is displayed. To suppress the display, specify the NoDetails parameter in the export and import cmdlet.
Generally, a script stops execution when an error is encountered, and you can run the cmdlet again after clearing the error conditions.
Conditions that are not considered errors are logged; many are reported as warnings, and script execution continues. For example, unsupported
application types are reported as warnings and are not imported. Applications that already exist in the XenApp 7.6 site are not imported. Policy settings
that are deprecated in XenApp 7.6 are not imported.
T he migration scripts use many PowerShell cmdlets, and all possible errors might not be logged. For additional logging coverage, use the PowerShell
logging features. For example, PowerShell transcripts log everything that is printed to the screen. For more information, see the help for the StartTranscript and Stop-Transcript cmdlets.
To migrate, you must use the Citrix XenApp 6.5 SDK. Download that SDK from https://www.citrix.com/downloads/xenapp/sdks/powershell-sdk.html.
Important: Remember to review this entire article before beginning a migration.
You should understand basic PowerShell concepts about execution policy, modules, cmdlets, and scripts. Although extensive scripting expertise is not required, you should understand the cmdlets you
execute. Use the Get-Help cmdlet to review each migration cmdlet's help before executing it. For example:
Get-Help -full Import-XAFarm
Specify a log file on the command line and always review the log file after running a cmdlet. If a script fails, check and fix the error identified in the log file and then run the cmdlet again.
Good to know:
To facilitate application delivery while two deployments are running (the XenApp 6.x farm and the new XenApp 7.6 site), you can aggregate both deployments in StoreFront or Web Interface. See the
eDocs documentation for your StoreFront or Web Interface release (Manage > Create a store).
Application icon data is handled in one of two ways:
If you specify the EmbedIconData parameter in the Export-XAFarm cmdlet, exported application icon data is embedded in the output XML file.
If you do not specify the EmbedIconData parameter in the Export-XAFarm cmdlet, exported application icon data is stored under a folder named by appending the string "-icons" to the base name
of the output XML file. For example, if the XmlOutputFile parameter is "FarmData.xml" then the folder "FarmData-icons" is created to store the application icons.
The icon data files in this folder are .txt files that are named using the browser name of the published application (although the files are .txt files, the stored data is encoded binary icon data, which
can be read by the import script to re-create the application icon). During the import operation, if the icon folder is not found in the same location as the import XML file, generic icons are used for
each imported application.
The names of the script modules, manifest files, shared module, and cmdlets are similar. Use tab completion with care to avoid errors. For example, Export-XAFarm is a cmdlet. ExportXAFarm.psd1
and ExportXAFarm.psm1 are files that cannot be executed.
In the step-by-step sections below, most <string> parameter values show surrounding quotation marks. These are optional for single-word strings.
For exporting from the XenApp 6.x server:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.295
The export must be run on a XenApp 6.x server configured with the controller and session-host (commonly known as controller) server mode.
To run the export cmdlets, you must be a XenApp administrator with permission to read objects. You must also have sufficient Windows permission to run PowerShell scripts; the step-by-step
procedures below contain instructions.
Ensure the XenApp 6.x farm is in a healthy state before beginning an export. Back up the farm database. Verify the farm's integrity using the Citrix IMA Helper utility (CTX133983): from the IMA
Datastore tab, run a Master Check (and then use the DSCheck option to resolve invalid entries). Repairing issues before the migration helps prevent export failures. For example, if a server was
removed improperly from the farm, its data might remain in the database; that could cause cmdlets in the export script to fail (for example, Get-XAServer -ZoneName). If the cmdlets fail, the script fails.
You can run the export cmdlets on a live farm that has active user connections; the export scripts read only the static farm configuration and policy data.
For importing to the XenApp 7.6 server:
You can import data to XenApp 7.6 deployments (and later supported versions). You must install a XenApp 7.6 Controller and Studio, and create a site before importing the data you exported from the
XenApp 6.x farm. Although VDAs are not required to import settings, they allow application file types to be made available.
To run the import cmdlets, you must be a XenApp administrator with permission to read and create objects. A Full Administrator has these permissions. You must also have sufficient Windows
permission to run PowerShell scripts; the step-by-step procedures below contain instructions.
No other user connections should be active during an import. The import scripts create many new objects, and disruptions may occur if other users are changing the configuration at the same time.
Remember that you can export data and then use the -Preview parameter with the import cmdlets to see what would happen during an actual import, but without actually importing anything. The logs will
indicate exactly what would happen during an actual import; if errors occur, you can resolve them before starting an actual import.
A video of an export walk-through is available here.
Complete the following steps to export data from a XenApp 6.x controller to XML files.
1. Download the XAMigration.zip migration tool package from the Citrix download site. For convenience, place it on a network file share that can be
accessed by both the XenApp 6.x farm and the XenApp 7.6 site. Unzip XAMigration.zip on the network file share. T here should be two zip files:
ReadIMA.zip and ImportFMA.zip.
2. Log on to the XenApp 6.x controller as a XenApp administrator with at least read-only permission and Windows permission to run PowerShell scripts.
3. Copy ReadIMA.zip from the network file share to the XenApp 6.x controller. Unzip and extract ReadIMA.zip on the controller to a folder (for example:
C:\XAMigration).
4. Open a PowerShell console and set the current directory to the script location. For example:
cd C:\XAMigration
5. Check the script execution policy by running Get-ExecutionPolicy.
6. Set the script execution policy to at least RemoteSigned to allow the scripts to be executed. For example:
Set-ExecutionPolicy RemoteSigned
7. Import the module definition files ExportPolicy.psd1 and ExportXAFarm.psd1:
Import-Module .\ExportPolicy.psd1
Import-Module .\ExportXAFarm.psd1
Good t o know :
If you intend to export only policy data, you can import only the ExportPolicy.psd1 module definition file. Similarly, if you intend to export only farm
data, import only ExportXAFarm.psd1.
Importing the module definition files also adds the required PowerShell snap-ins.
Do not import the .psm1 script files.
8. T o export policy data, run the Export-Policy cmdlet.
P aramet er
Descript ion
-
XML output file name; this file will hold the exported data. Must have an .xml extension. T he file must not exist, but if a path is
XmlOutputFile
specified, the parent path must exist.
"<string>.xml"
Default: None; this parameter is required.
-LogFile "
Log file name. An extension is optional. T he file is created if it does not exist. If the file exists and the NoClobber parameter is
<string>"
also specified, an error is generated; otherwise, the file's content is overwritten.
Default: See Logging and error handling
-NoLog
Do not generate log output. T his overrides the LogFile parameter if it is also specified.
Default: False; log output is generated
-NoClobber
Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no
effect.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.296
P aramet er
Default: False; an existing log file is overwritten
Descript ion
-NoDetails
Do not send detailed reports about script execution to the console.
Default: False; detailed reports are sent to the console
-
Do not print the message "XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#" to the console.
SuppressLogo
T his message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting
this parameter.
Default: False; the message is printed to the console
Example: T he following cmdlet exports policy information to the XML file named MyPolicies.xml. T he operation is logged to the file named
MyPolicies.log.
Export-Policy -XmlOutputFile ".\MyPolicies.XML"
-LogFile ".\MyPolicies.Log"
9. T o export farm data, run the Export-XAFarm cmdlet, specifying a log file and an XML file.
P aramet er
Descript ion
-XmlOutputFile
XML output file name; this file will hold the exported data. Must have an .xml extension. T he file must not exist, but if a path is
"<string>.xml"
specified, the parent path must exist.
Default: None; this parameter is required.
-LogFile "
Log file name. An extension is optional. T he file is created if it does not exist. If the file exists and the NoClobber parameter is
<string>"
also specified, an error is generated; otherwise, the file's content is overwritten.
Default: See Logging and error handling
-NoLog
Do not generate log output. T his overrides the LogFile parameter if it is also specified.
Default: False; log output is generated
-NoClobber
Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no
effect.
Default: False; an existing log file is overwritten
-NoDetails
Do not send detailed reports about script execution to the console.
Default: False; detailed reports are sent to the console
-SuppressLogo
Do not print the message "XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#" to the
console. T his message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends
omitting this parameter.
Default: False; the message is printed to the console
-IgnoreAdmins
Do not export administrator information. See Advanced use for how-to-use information.
Default: False; administrator information is exported
-IgnoreApps
Do not export application information. See Advanced use for how-to-use information.
Default: False; application information is exported
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.297
P aramet er
Descript ion
-IgnoreServers
Do not export server information.
Default: False: server information is exported
-IgnoreZones
Do not export zone information.
Default: False; zone information is exported.
-IgnoreOthers
Do not export information such as configuration logging, load evaluators, load balancing policies, printer drivers, and worker
groups.
Default: False; other information is exported
Note: T he purpose of the -IgnoreOthers switch is to allow you to proceed with an export when an error exists that would not
affect the actual data being used for the exporting or importing process.
-AppLimit
<integer>
EmbedIconData
-SkipApps
<integer>
Number of applications to be exported. See Advanced use for how-to-use information.
Default: All applications are exported
Embed application icon data in the same XML file as the other objects.
Default: Icons are stored separately. See Requirements, preparation, and best practices for details
Number of applications to skip. See Advanced use for how-to-use information.
Default: No applications are skipped
Example: T he following cmdlet exports farm information to the XML file named MyFarm.xml. T he operation is logged to the file MyFarm.log. A folder
named "MyFarm-icons" is created to store the application icon data files; this folder is at the same location as MyFarm.XML.
Export-XAFarm -XmlOutputFile ".\MyFarm.XML" -LogFile ".\MyFarm.Log"
After the export scripts complete, the XML files specified on the command lines contain the policy and XenApp farm data. T he application icon files
contain icon data files, and the log file indicate what occurred during the export.
A video of an import walk-through is available here.
Remember that you can run a preview import (by issuing the Import-Policy or Import-XAFarm cmdlet with the Preview parameter) and review the log files
before performing an actual import.
Complete the following steps to import data to a XenApp 7.6 site, using the XML files generating from the export.
1. Log on to the XenApp 7.6 controller as an administrator with read-write permission and Windows permission to run PowerShell scripts.
2. If you have not unzipped the migration tool package XAMigration on the network file share, do so now. Copy ImportFMA.zip from the network file
share to the XenApp 7.6 Controller. Unzip and extract ImportFMA.zip on the Controller to a folder (for example: C:\XAMigration).
3. Copy the XML files (the output files generated during the export) from the XenApp 6.x controller to the same location on the XenApp 7.6 Controller
where you extracted the ImportFMA.zip files.
If you chose not to embed the application icon data in the XML output file when you ran the Export-XAFarm cmdlet, be sure to copy the icon data
folder and files to the same location on the XenApp 7.6 controller as the output XML file containing the application data and the extracted
ImportFMA.zip files.
4. Open a PowerShell console and set the current directory to the script location.
cd C:\XAMigration
5. Check the script execution policy by running Get-ExecutionPolicy.
6. Set the script execution policy to at least RemoteSigned to allow the scripts to be executed. For example:
Set-ExecutionPolicy RemoteSigned
7. Import the PowerShell module definition files ImportPolicy.psd1 and ImportXAFarm.psd1:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.298
Import-Module .\ImportPolicy.psd1
Import-Module .\ImportXAFarm.psd1
Good t o know :
If you intend to import only policy data, you can import only the ImportPolicy.psd1 module definition file. Similarly, if you intend to import only farm
data, import only ImportXAFarm.psd1.
Importing the module definition files also adds the required PowerShell snap-ins.
Do not import the .psm1 script files.
8. T o import policy data, run the Import-Policy cmdlet, specifying the XML file containing the exported policy data.
P aramet er
Descript ion
-XmlInputFile
XML input file name; this file contains data collected from running the Export-Policy cmdlet. Must have an .xml extension.
"<string>.xml"
Default: None; this parameter is required.
-XsdFile "
XSD file name. T he import scripts use this file to validate the syntax of the XML input file. See Advanced use for how-to-use
<string>"
information.
Default: PolicyData.XSD
-LogFile "
<string>"
-NoLog
Log file name. If you copied the export log files to this server, consider using a different log file name with the import cmdlet.
Default: See Logging and error handling
Do not generate log output. T his overrides the LogFile parameter, if it is also specified.
Default: False; log output is generated
-NoClobber
Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no effect.
Default: False; an existing log file is overwritten
-NoDetails
Do not send detailed reports about script execution to the console.
Default: False; detailed reports are sent to the console
-
Do not print the message "XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#" to the console.
SuppressLogo
T his message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting this
parameter.
Default: False; the message is printed to the console
-Preview
Perform a preview import: read data from the XML input file, but do not import objects to the site. T he log file and console
indicate what occurred during the preview import. A preview shows administrators what would happen during a real import.
Default: False; a real import occurs
Example: T he folowing cmdlet imports policy data from the XML file named MyPolcies.xml. T he operation is logged to the file named MyPolicies.log.
Import-Policy -XmlInputFile ".\MyPolicies.XML"
-LogFile ".\MyPolicies.Log"
9. T o import applications, run the Import-XAFarm cmdlet, specifying a log file and the XML file containing the exported farm data.
P aramet er
Descript ion
-XmlInputFile "
XML input file name; this file contains data collected from running the Export-XAFarm cmdlet. Must have an .xml
<string>.xml"
extension.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.299
P aramet er
Default: None; this parameter is required.
Descript ion
-XsdFile "<string>"
XSD file name. T he import scripts use this file to validate the syntax of the XML input file. See Advanced use for howto-use information.
Default: XAFarmData.XSD
-LogFile "<string>"
Log file name. If you copied the export log files to this server, consider using a different log file name with the import
cmdlet.
Default: See Logging and error handling
-NoLog
Do not generate log output. T his overrides the LogFile parameter, if it is also specified.
Default: False; log output is generated
-NoClobber
Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has
no effect.
Default: False; an existing log file is overwritten
-NoDetails
Do not send detailed reports about script execution to the console.
Default: False; detailed reports are sent to the console
-SuppressLogo
Do not print the message "XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#" to the
console. T his message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix
recommends omitting this parameter.
Default: False; the message is printed to the console
-Preview
Perform a preview import: read data from the XML input file, but do not import objects to the site. T he log file and
console indicate what occurred during the preview import. A preview shows administrators what would happen during a
real import.
Default: False; a real import occurs
-DeliveryGroupName "
<string>"
-MatchFolder "<string>"
Delivery Group name for all imported applications. See Advanced use for how-to-use information.
Default: "<xenapp-farm-name> - Delivery Group"
Import only those applications in folders with names that match the string. See Advanced use for how-to-use
information.
Default: No matching occurs
-NotMatchFolder "
Import only those applications in folders with names that do not match the string. See Advanced use for how-to-use
<string>"
information.
Default: No matching occurs
-MatchServer "<string>"
Import only those applications from servers whose names match the string. See Advanced use for how-to-use
information.
-NotMatchServer "
https://docs.citrix.com
Import only those applications from servers whose names do not match the string. See Advanced use for how-to-use
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.300
<string>"
P aramet er
information.
Descript ion
Default: No matching occurs
-MatchWorkerGroup "
Import only those applications published to worker groups with names that match the string. See Advanced use for
<string>"
how-to-use information.
Default: No matching occurs
-
Import only those applications published to worker groups with names that do not match the string. See Advanced use
NotMatchWorkerGroup
for how-to-use information.
"<string>"
Default: No matching occurs
-MatchAccount "
Import only those applications published to user accounts with names that match the string. See Advanced use for
<string>"
how-to-use information.
Default: No matching occurs
-NotMatchAccount "
Import only those applications published to user accounts with names that do not match the string. See Advanced use
<string>"
for how-to-use information.
Default: No matching occurs
-IncludeStreamedApps
Import applications of type "StreamedToClientOrServerInstalled" . (No other streamed applications are imported.)
Default: Streamed applications are not imported
-IncludeDisabledApps
Import applications that have been marked as disabled.
Default: Disabled applications are not imported
Example: T he following cmdlet imports applications from the XML file named MyFarm.xml. T he operation is logged to the file named MyFarm.log.
Import-XAFarm -XmlInputFile ".\MyFarm.XML"
-LogFile ".\MyFarm.Log"
10. After the import completes successfully, complete the post-migration tasks.
After successfully importing XenApp 6.x policies and farm settings into a XenApp 7.6 site, use the following guidance to ensure that the data has been
imported correctly.
P olicies and policy set t ings
Importing policies is essentially a copy operation, with the exception of deprecated settings and policies, which are not imported. T he post-migration
check essentially involves comparing the two sides.
1. T he log file lists all the policies and settings imported and ignored. First, review the log file and identify which settings and policies were not
imported.
2. Compare the XenApp 6.x policies with the policies imported to XenApp 7.6. T he values of the settings should remain the same (except for
deprecated policy settings, as noted in the next step).
If you have a small number of policies, you can perform a side-by-side visual comparison of the policies displayed in the XenApp 6.x AppCenter
and the policies displayed in the XenApp 7.6 Studio.
If you have a large number of policies, a visual comparison might not be feasible. In such cases, use the policy export cmdlet (Export-Policy) to
export the XenApp 7.6 policies to a different XML file, and then use a text diff tool (such as windiff) to compare that file’s data to the data in
the XML file used during the policy export from XenApp 6.x.
3. Use the information in the Policy settings not imported section to determine what might have changed during the import. If a XenApp 6.x policy
contains only deprecated settings, as a whole policy, it is not imported. For example, if a XenApp 6.x policy contains only HMR test settings, that
policy is completely ignored because there is no equivalent setting supported in XenApp 7.6.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.301
Some XenApp 6.x policy settings are no longer supported, but the equivalent functionality is implemented in XenApp 7.6. For example, in XenApp
7.6, you can configure a restart schedule for Server OS machines by editing a Delivery Group; this functionality was previously implemented through
policy settings.
4. Review and confirm how filters will apply to your XenApp 7.6 site versus their use in XenApp 6.x; significant differences between the XenApp 6.x
farm and the XenApp 7.6 site could change the effect of filters.
F ilt ers
Carefully examine the filters for each policy. Changes may be required to ensure they still work in XenApp 7.6 as originally intended in XenApp 6.x.
F ilt er
Considerat ions
Access
Access Control Should contain the same values as the original XenApp 6.x filters and should work without requiring changes.
Control
Citrix
A simple Boolean; should work without requiring changes. (T his product is now known as NetScaler SD-WAN.)
CloudBridge
Client IP
Lists client IP address ranges; each range is either allowed or denied. T he import script preserves the values, but they may require
Address
changes if different clients connect to the XenApp 7.6 VDA machines.
Client Name
Similar to the Client IP Address filter, the import script preserves the values, but they may require changes if different clients
connect to the XenApp 7.6 VDA machines.
Organizational
Values might be preserved, depending on whether or not the OUs can be resolved at the time they are imported. Review this
Unit
filter closely, particularly if the XenApp 6.x and XenApp 7.6 machines reside in different domains. If you do not configure the filter
values correctly, the policy may be applied to an incorrect set of OUs.
T he OUs are represented by names only, so there is a small chance that an OU name will be resolved to an OU containing
different members from the OUs in the XenApp 6.x domain. Even if some of the values of the OU filter are preserved, you should
carefully review the values.
User or Group
Values might be preserved, depending on whether or not the accounts can be resolved at the time they are imported.
Similar to OUs, the accounts are resolved using names only, so if the XenApp 7.6 site has a domain with the same domain and
user names, but are actually two different domains and users, the resolved accounts could be different from the XenApp 6.x
domain users. If you do not properly review and modify the filter values, incorrect policy applications can occur.
Worker Group
Worker groups are not supported in XenApp 7.6. Consider using the Delivery Group, Delivery Group T ype, and T ag filters, which
are supported in XenApp 7.6 (not in XenApp 6.x).
Delivery Group: Allows policies to be applied based on Delivery Groups. Each filter entry specifies a Delivery Group and can be
allowed or denied.
Delivery Group T ype: Allows policies to be applied based on the Delivery Group types. Each filter specifies a Delivery Group
type that can be allowed or denied.
T ag: Specifies policy application based on tags created for the VDA machines. Each tag can be allowed or denied.
To recap, filters that involve domain user changes require the most attention if the XenApp 6.x farm and the XenApp 7.6 site are in different domains.
Because the import script uses only strings of domain and user names to resolve users in the new domain, some of the accounts might be resolved
and others might not. While there is only a small chance that different domains and users have the same name, you should carefully review these
filters to ensure they contain correct values.
Applicat ions
T he application importing scripts do not just import applications; they also create objects such as Delivery Groups. If the application import involves
multiple iterations, the original application folder hierarchies can change significantly.
1. First, read the migration log files that contain details about which applications were imported, which applications were ignored, and the cmdlets
that were used to create the applications.
2. For each application:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.302
Visually check to ensure the basic properties were preserved during the import. Use the information in the Application property mapping section
to determine which properties were imported without change, not imported, or initialized using the XenApp 6.x application data.
Check the user list. T he import script automatically imports the explicit list of users into the application's limit visibility list in XenApp 7.6. Check to
ensure that the list remains the same.
3. Application servers are not imported. T his means that none of the imported applications can be accessed yet. T he Delivery Groups that contain
these applications must be assigned machine catalogs that contain the machines that have the published applications’ executable images. For
each application:
Ensure that the executable name and the working directory point to an executable that exists in the machines assigned to the Delivery Group
(through the machine catalogs).
Check a command line parameter (which may be anything, such as file name, environment variable, or executable name). Verify that the
parameter is valid for all the machines in the machine catalogs assigned to the Delivery Group.
Log f iles
T he log files are the most important reference resources for an import and export. T his is why existing log files are not overwritten by default, and
default log file names are unique.
As noted in the “Logging and error handling” section, if you chose to use additional logging coverage with the PowerShell Start-Transcript and StopTranscript cmdlets (which record everything typed and printed to the console), that output, together with the log file, provides a complete reference
of import and export activity.
Using the time stamps in the log files, you can diagnose certain problems. For example, if an export or import ran for a very long time, you could
determine if a faulty database connection or resolving user accounts took most of the time.
T he commands recorded in the log files also tell you how some objects are read or created. For example, to create a Delivery Group, several
commands are executed to not only create the Delivery Group object itself, but also other objects such as access policy rules that allow application
objects to be assigned to the Delivery Group.
T he log file can also be used to diagnose a failed export or import. Typically, the last lines of the log file indicate what caused the failure; the failure
error message is also saved in the log file. Together with the XML file, the log file can be used to determine which object was involved in the failure.
After reviewing and testing the migration, you can:
1. Upgrade your XenApp 6.5 worker servers to current Virtual Delivery Agents (VDAs) by running the 7.6 installer on the server, which removes the XenApp
6.5 software and then automatically installs a current VDA. See Upgrade a XenApp 6.5 worker to a new VDA for Windows Server OS for instructions.
For XenApp 6.0 worker servers, you must manually uninstall the XenApp 6.0 software from the server. You can then use the 7.6 installer to install the
current VDA. You cannot use the 7.6 installer to automatically remove the XenApp 6.0 software.
2. From Studio in the new XenApp site, create machine catalogs (or edit existing catalogs) for the upgraded workers.
3. Add the upgraded machines from the machine catalog to the Delivery Groups that contain the applications installed on those VDAs for Windows
Server OS.
By default, the Export-Policy cmdlet exports all policy data to an XML file. Similarly, Export-XAFarm exports all farm data to an XML file. You can use
command line parameters to more finely control what is exported and imported.
Export applicat ions part ially - If you have a large number of applications and want to control how many are exported to the XML file, use the
following parameters:
AppLimit - Specifies the number of applications to export.
SkipApps - Specifies the number of applications to skip before exporting subsequent applications.
You can use both of these parameters to export large quantities of applications in manageable chunks. For example, the first time you run ExportXAFarm, you want to export only the first 200 applications, so you specify that value in the AppLimit parameter.
Export-XAFarm -XmlOutputFile "Apps1-200.xml"
-AppLimit "200"
T he next time you run Export-XAFarm, you want to export the next 100 applications, so you use the SkipApps parameter to disregard the
applications you've already exported (the first 200), and the AppLimit parameter to export the next 100 applications.
Export-XAFarm -XmlOutputFile "Apps201-300.xml"
-AppLimit "100" -SkipApps "200"
Do not export cert ain object s - Some objects can be ignored and thus do not need to be exported, particularly those objects that are not
imported; see Policy settings not imported and Application property mapping. Use the following parameters to prevent exporting unneeded objects:
IgnoreAdmins - Do not export administrator objects
IgnoreServers - Do not export server objects
IgnoreZones - Do not export zone objects
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.303
IgnoreOthers - Do not export configuration logging, load evaluator, load balancing policy, printer driver, and worker group objects
IgnoreApps - Do not export applications; this allows you to export other data to an XML output file and then run the export again to export
applications to a different XML output file.
You can also use these parameters to work around issues that could cause the export to fail. For example, if you have a bad server in a zone, the
zone export might fail; if you include the IgnoreZones parameter, the export continues with other objects.
Delivery Group names - If you do not want to put all of your applications into one Delivery Group (for example, because they are accessed by
different sets of users and published to different sets of servers), you can run Import-XAFarm multiple times, specifying different applications and a
different Delivery Group each time. Although you can use PowerShell cmdlets to move applications from one Delivery Group to another after the
migration, importing selectively to unique Delivery Groups can reduce or eliminate the effort of moving the applications later.
1. Use the DeliveryGroupName parameter with the Import-XAFarm cmdlet. T he script creates the specified Delivery Group if it doesn't exist.
2. Use the following parameters with regular expressions to filter the applications to be imported into the Delivery Group, based on folder, worker
group, user account, and/or server names. Enclosing the regular expression in single or double quotation marks is recommended. For information
about regular expressions, see http://msdn.microsoft.com/en-us/library/hs600312(v=vs.110).aspx.
MatchWorkerGroup and NotMatchWorkerGroup - For example, for applications published to worker groups, the following cmdlet imports
applications in the worker group named "Productivity Apps" to a XenApp 7.6 Delivery Group of the same name:
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log
–MatchWorkerGroup ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’
MatchFolder and NotMatchFolder - For example, for applications organized in application folders, the following cmdlet imports applications in
the folder named "Productivity Apps" to a XenApp 7.6 Delivery Group of the same name.
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchFolder ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’
For example, the following cmdlet imports applications in any folder whose name contains "MS Office Apps" to the default Delivery Group.
Import-XAFarm -XmlInputFile .\THeFarmApps.XML -MatchFolder ".*/MS Office Apps/.*"
MatchAccount and NotMatchAccount - For example, for applications published to Active Directory users or user groups, the following cmdlet
imports applications published to the user group named "Finance Group" to a XenApp 7.6 Delivery Group named "Finance."
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log
–MatchAccount ‘DOMAIN\\Finance Group’ –DeliveryGroupName ‘Finance’
MatchServer and NotMatchServer - For example, for applications organized on servers, the following cmdlet imports applications associated
with the server not named "Current" to a XenApp Delivery Group named "Legacy."
Import-XAFarm -XmlInputFile XAFarm.xml -LogFile XAFarmImport.log
-NotMatchServer 'Current' -DeliveryGroupName 'Legacy'
Cust omizat ion - PowerShell programmers can create their own tools. For example, you can use the export script as an inventory tool to keep track
of changes in a XenApp 6.x farm. You can also modify the XSD files or (create your own XSD files) to store additional data or data in different
formats in the XML files. You can specify a nondefault XSD file with each of the import cmdlets.
Note: Although you can modify script files to meet specific or advanced migration requirements, support is limited to the scripts in their unmodified
state. Citrix T echnical Support will recommend reverting to the unmodified scripts to determine expected behavior and provide support, if necessary.
If you are using PowerShell version 2.0 and you added the Citrix Group Policy PowerShell Provider snap-in or the Citrix Common Commands snap-in
using the Add-PSSnapIn cmdlet, you might see the error message "Object reference not set to an instance of an object" when you run the export or
import cmdlets. T his error does not affect script execution and can be safely ignored.
Avoid adding or removing the Citrix Group Policy PowerShell Provider snap-in in the same console session where the export and import script modules
are used, because those script modules automatically add the snap-in. If you add or remove the snap-in separately, you might see one of the
following errors:
"A drive with the name 'LocalGpo' already exists." T his error appears when the snap-in is added twice; the snap-in attempts to mount the drive
LocalGpo when it's loaded, and then reports the error.
"A parameter cannot be found that matches parameter name 'Controller'." T his error appears when the snap-in has not been added but the script
attempts to mount the drive. T he script is not aware that the snap-in was removed. Close the console and launch a new session. In the new
session, import the script modules; do not add or remove the snap-in separately.
When importing the modules, if you right-click a .psd1 file and select Open or Open with PowerShell, the PowerShell console window will rapidly open
and close until you stop the process. T o avoid this error, enter the complete PowerShell script module name directly in the PowerShell console
window (for example, Import-Module .\ExportPolicy.psd1).
If you receive a permission error when running an export or import, ensure you are a XenApp administrator with permission to read objects (for export)
or read and create objects (for import). You must also have sufficient Windows permission to run PowerShell scripts.
If an export fails, check that the XenApp 6.x farm is in a healthy state by running the DSMAINT and DSCHECK utilities on the XenApp 6.x controller
server.
If you run a preview import and then later run the import cmdlets again for an actual migration, but discover that nothing was imported, verify that
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.304
you removed the Preview parameter from the import cmdlets.
T he following computer and user policy settings are not imported because they are no longer supported. Please note, unfiltered policies are never
imported. T he features and components that support these settings have either been replaced by new technologies/components or the settings do
not apply because of architectural and platform changes.
Comput er policy set t ings not import ed
Connection access control
CPU management server level
DNS address resolution
Farm name
Full icon caching
Health monitoring, Health monitoring tests
License server host name, License server port
Limit user sessions, Limits on administrator sessions
Load evaluator name
Logging of logon limit events
Maximum percent of servers with logon control
Memory optimization, Memory optimization application exclusion list, Memory optimization interval, Memory optimization schedule: day of month,
Memory optimization schedule: day of week, Memory optimization schedule: time
Offline app client trust, Offline app event logging, Offline app license period, Offline app users
Prompt for password
Reboot custom warning, Reboot custom warning text, Reboot logon disable time, Reboot schedule frequency, Reboot schedule randomization
interval, Reboot schedule start date, Reboot schedule time, Reboot warning interval, Reboot warning start time, Reboot warning to users, Scheduled
reboots
Shadowing *
T rust XML requests (configured in StoreFront)
Virtual IP adapter address filtering, Virtual IP compatibility programs list, Virtual IP enhanced compatibility, Virtual IP filter adapter addresses programs
list
Workload name
XenApp product edition, XenApp product model
XML service port
* Replaced with Windows Remote Assistance
User policy set t ings not import ed
Auto connect client COM ports, Auto connect client LPT ports
Client COM port redirection, Client LPT port redirection
Client printer names
Concurrent logon limit
Input from shadow connections *
Linger disconnect timer interval, Linger terminate timer interval
Log shadow attempts *
Notify user of pending shadow connections *
Pre-launch disconnect timer interval, Pre-launch terminate timer interval
Session importance
Single Sign-On, Single Sign-On central store
Users who can shadow other users, Users who cannot shadow other users *
* Replaced with Windows Remote Assistance
T he following application types are not imported.
Server desktops
Content
Streamed applications (App-V is the new method used for streaming applications)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.305
T he farm data import script imports only applications. T he following application properties are imported without change.
IMA P ropert y
F MA P ropert y
AddT oClientDesktop
ShortcutAddedT oDesktop
AddT oClientStartMenu
ShortcutAddedT oStartMenu
ClientFolder
ClientFolder
CommandLineExecutable
CommandLineExecutable
CpuPriorityLevel
CpuPriorityLevel
Description
Description
DisplayName
PublishedName
Enabled
Enabled
StartMenuFolder
StartMenuFolder
WaitOnPrinterCreation
WaitForPrinterCreation
WorkingDirectory
WorkingDirectory
FolderPath
AdminFolderName
Note: IMA and FMA have different restrictions on folder name length. In IMA, the folder name limit is 256 characters; the FMA limit is 64 characters.
When importing, applications with a folder path containing a folder name of more than 64 characters are skipped. T he limit applies only to the folder
name in the folder path; the entire folder path can be longer than the limits noted. T o avoid applications from being skipped during the import, Citrix
recommends checking the application folder name length and shortening it, if needed, before exporting.
T he following application properties are initialized or uninitialized by default, or set to values provided in the XenApp 6.x data:
F MA P ropert y
Value
Name
Initialized to the full path name, which contains the IMA properties FolderPath and DisplayName, but stripped
of the leading string "Applications\"
ApplicationT ype
HostedOnDesktop
CommandLineArguments
Initialized using the XenApp 6.x command line arguments
IconFromClient
Uninitialized; defaults to false
IconUid
Initialized to an icon object created using XenApp 6.x icon data
SecureCmdLineArgumentsEnabled
Uninitialized; defaults to true
UserFilterEnabled
Uninitialized; defaults to false
UUID
Read-only, assigned by the Controller
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.306
F MA P ropert y
Visible
Value
Uninitialized; defaults to true
T he following application properties are partially migrated:
IMA
Comment s
P ropert y
FileT ypes
Only the file types that exist on the new XenApp site are migrated. File types that do not exist on the new site are ignored. File types
are imported only after the file types on the new site are updated.
IconData
New icon objects are created if the icon data has been provided for the exported applications.
Accounts
T he user accounts of an application are split between the user list for the Delivery Group and the application. Explicit users are used to
initialize the user list for the application. In addition, the "Domain Users" account for the domain of the user accounts is added to the
user list for the Delivery Group.
T he following XenApp 6.x properties are not imported:
IMA P ropert y
Comment s
ApplicationT ype
Ignored.
HideWhenDisabled
Ignored.
AccessSessionConditions
Replaced by Delivery Group access policies.
AccessSessionConditionsEnabled
Replaced by Delivery Group access policies.
ConnectionsT hroughAccessGatewayAllowed
Replaced by Delivery Group access policies.
OtherConnectionsAllowed
Replaced by Delivery Group access policies.
AlternateProfiles
FMA does not support streamed applications.
OfflineAccessAllowed
FMA does not support streamed applications.
ProfileLocation
FMA does not support streamed applications.
ProfileProgramArguments
FMA does not support streamed applications.
ProfileProgramName
FMA does not support streamed applications.
RunAsLeastPrivilegedUser
FMA does not support streamed applications.
AnonymousConnectionsAllowed
FMA uses a different technology to support unauthenticated (anonymous) connections.
ApplicationId, SequenceNumber
IMA-unique data.
AudioT ype
FMA does not support advanced client connection options.
EncryptionLevel
SecureICA is enabled/disabled in Delivery Groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.307
IMA P ropert y
EncryptionRequired
Comment s
SecureICA is enabled/disabled in Delivery Groups.
SslConnectionEnabled
FMA uses a different T LS implementation.
ContentAddress
FMA does not support published content.
ColorDepth
FMA does not support advanced window appearances.
MaximizedOnStartup
FMA does not support advanced window appearances.
T itleBarHidden
FMA does not support advanced window appearances.
WindowsT ype
FMA does not support advanced window appearances.
InstanceLimit
FMA does not support application limits.
MultipleInstancesPerUserAllowed
FMA does not support application limits.
LoadBalancingApplicationCheckEnabled
FMA uses a different technology to support load balancing.
PreLaunch
FMA uses a different technology to support session prelaunch.
CachingOption
FMA uses a different technology to support session prelaunch.
ServerNames
FMA uses a different technology.
WorkerGroupNames
FMA does not support worker groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.308
Secure
Nov 28 , 20 17
XenApp and XenDesktop offer a secure-by-design solution that allows you to tailor your environment to your security
needs.
One security concern IT faces with mobile workers is lost or stolen data. By hosting applications and desktops, XenApp and
XenDesktop securely separate sensitive data and intellectual property from end-point devices by keeping all data in a data
center. When policies are enabled to allow data transfer, all data is encrypted.
T he XenDesktop and XenApp data centers also make incident response easier with a centralized monitoring and
management service. Director allows IT to monitor and analyze data that is being accessed around the network, and
Studio allows IT to patch and remedy most vulnerabilities in the data center instead of fixing the problems locally on each
end-user device.
XenApp and XenDesktop also simplify audits and regulatory compliance because investigators can use a centralized audit
trail to determine who accessed what applications and data. Director gathers historical data regarding updates to the
system and user data usage by accessing Configuration Logging and OData API.
Delegated Administration allows you to set up administrator roles to control access to XenDesktop and XenApp at a
granular level. T his allows flexibility in your organization to give certain administrators full access to tasks, operations, and
scopes while other administrators have limited access.
XenApp and XenDesktop give administrators granular control over users by applying policies at different levels of the
network - from the local level to the Organizational Unit level. T his control of policies determines if a user, device, or groups
of users and devices can connect, print, copy/paste, or map local drives, which could minimize security concerns with thirdparty contingency workers. Administrators can also use the Desktop Lock feature so end users can only use the virtual
desktop while preventing any access to the local operating system of the end-user device.
Administrators can increase security on XenApp or XenDesktop by configuring the Site to use the Transport Layer Security
(T LS) protocol of the Controller or between end users and Virtual Delivery Agents (VDA). T he protocol can also be enabled
on a Site to provide server authentication, data stream encryption, and message integrity checks for a TCP/IP connection.
XenApp and XenDesktop also support multifactor authentication for Windows or a specific application. Multifactor
authentication could also be used to manage all resources delivered by XenApp and XenDesktop. T hese methods include:
T okens
Smart cards
RADIUS
Kerberos
Biometrics
XenDesktop can be integrated with many third-party security solutions, ranging from identity management to antivirus
software. A list of supported products can be found at http://www.citrix.com/ready.
Select releases of XenApp and XenDesktop are certified for Common Criteria standard. For a list of those standards, go to
http://www.commoncriteriaportal.org/cc/.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.309
Security considerations and best practices
Nov 28 , 20 17
T his document describes:
General security best practices when using this release, and any security-related differences between this release and a
conventional computer environment
Manage user accounts
Manage user privileges
Manage logon rights
Configure user rights
Configure service settings
Deployment scenarios and their security implications
Remote PC Access security considerations
Your organization may need to meet specific security standards to satisfy regulatory requirements. T his document does not
cover this subject, because such security standards change over time. For up-to-date information on security standards and
Citrix products, consult http://www.citrix.com/security/.
Security best practices
Keep all machines in your environment up to date with security patches. One advantage is that you can use thin clients as
terminals, which simplifies this task.
Protect all machines in your environment with antivirus software.
Consider using platform-specific anti-malware software such as the Microsoft Enhanced Mitigation Experience Toolkit
(EMET ) for Windows machines. Some authorities recommend using the latest Microsoft-supported version of EMET within
their regulated environments. Note that, according to Microsoft, EMET may not be compatible with some software, so it
should be thoroughly tested with your applications before deployment in a production environment. XenApp and
XenDesktop have been tested with EMET 5.5 in its default configuration. Currently, EMET is not recommended for use on a
machine that has a Virtual Delivery Agent (VDA) installed.
Protect all machines in your environment with perimeter firewalls, including at enclave boundaries as appropriate.
If you are migrating a conventional environment to this release, you may need to reposition an existing perimeter firewall or
add new perimeter firewalls. For example, suppose there is a perimeter firewall between a conventional client and database
server in the data center. When this release is used, that perimeter firewall must be placed so that the virtual desktop and
user device are on one side, and the database servers and Delivery Controllers in the data center are on the other side.
T herefore, consider creating an enclave within your data center to contain the database servers and Controllers. Also
consider having protection between the user device and the virtual desktop.
All machines in your environment should be protected by a personal firewall. When you install core components and VDAs,
you can choose to have the ports required for component and feature communication opened automatically if the
Windows Firewall Service is detected (even if the firewall is not enabled). You can also choose to configure those firewall
ports manually. If you use a different firewall, you must configure the firewall manually.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.310
Not e: TCP ports 1494 and 2598 are used for ICA and CGP and are therefore likely to be open at firewalls so that users
outside the data center can access them. Citrix recommends that you do not use these ports for anything else, to avoid
the possibility of inadvertently leaving administrative interfaces open to attack. Ports 1494 and 2598 are officially
registered with the Internet Assigned Number Authority (http://www.iana.org/).
All network communications should be appropriately secured and encrypted to match your security policy. You can secure
all communication between Microsoft Windows computers using IPSec; refer to your operating system documentation for
details about how to do this. In addition, communication between user devices and desktops is secured through Citrix
SecureICA, which is configured by default to 128-bit encryption. You can configure SecureICA when you are creating or
updating a Delivery Group.
Apply Windows best practice for account management. Do not create an account on a template or image before it is
duplicated by Machine Creation Services or Provisioning Services. Do not schedule tasks using stored privileged domain
accounts. Do not manually create shared Active Directory machine accounts. T hese practices will help prevent a machine
attack from obtaining local persistent account passwords and then using them to log on to MCS/PVS shared images
belonging to others.
Manage user privileges
Grant users only the capabilities they require. Microsoft Windows privileges continue to be applied to desktops in the usual
way: configure privileges through User Rights Assignment and group memberships through Group Policy. One advantage of
this release is that it is possible to grant a user administrative rights to a desktop without also granting physical control over
the computer on which the desktop is stored.
Note the following when planning for desktop privileges:
By default, when non-privileged users connect to a desktop, they see the time zone of the system running the desktop
instead of the time zone of their own user device. For information on how to allow users to see their local time when
using desktops, see the Manage Delivery Groups article.
A user who is an administrator on a desktop has full control over that desktop. If a desktop is a pooled desktop rather
than a dedicated desktop, the user must be trusted in respect of all other users of that desktop, including future users.
All users of the desktop need to be aware of the potential permanent risk to their data security posed by this situation.
T his consideration does not apply to dedicated desktops, which have only a single user; that user should not be an
administrator on any other desktop.
A user who is an administrator on a desktop can generally install software on that desktop, including potentially
malicious software. T he user can also potentially monitor or control traffic on any network connected to the desktop.
Manage logon rights
Logon rights are required for both user accounts and computer accounts. As with Microsoft Windows privileges, logon
rights continue to be applied to desktops in the usual way: configure logon rights through User Rights Assignment and
group memberships through Group Policy.
T he Windows logon rights are: log on locally, log on through Remote Desktop Services, log on over the network (access this
computer from the network), log on as a batch job, and log on as a service.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.311
For computer accounts, grant computers only the logon rights they require. T he logon right "Access this computer from the
network" is required:
At VDAs, for the computer accounts of Delivery Controllers
At Delivery Controllers, for the computer accounts of VDAs. See Active Directory OU-based Controller discovery.
At StoreFront servers, for the computer accounts of other servers in the same StoreFront server group
For user accounts, grant users only the logon rights they require.
According to Microsoft, by default the group Remote Desktop Users is granted the logon right "Allow log on through
Remote Desktop Services" (except on domain controllers).
Your organization's security policy may state explicitly that this group should be removed from that logon right. Consider
the following approach:
T he Virtual Delivery Agent (VDA) for Server OS uses Microsoft Remote Desktop Services. You can configure the Remote
Desktop Users group as a restricted group, and control membership of the group via Active Directory group policies.
Refer to Microsoft documentation for more information.
For other components of XenApp and XenDesktop, including the VDA for Desktop OS, the group Remote Desktop
Users is not required. So, for those components, the group Remote Desktop Users does not require the logon right
"Allow log on through Remote Desktop Services"; you can remove it. Additionally:
If you administer those computers via Remote Desktop Services, ensure that all such administrators are already
members of the Administrators group.
If you do not administer those computers via Remote Desktop Services, consider disabling Remote Desktop Services
itself on those computers.
Although it is possible to add users and groups to the login right "Deny logon through Remote Desktop Services", the use
of deny logon rights is not generally recommended. Refer to Microsoft documentation for more information.
Configure user rights
Delivery Controller installation creates the following Windows services:
Citrix AD Identity Service (NT SERVICE\CitrixADIdentityService): Manages Microsoft Active Directory computer accounts
for VMs.
Citrix Analytics (NT SERVICE\CitrixAnalytics): Collects site configuration usage information for use by Citrix, if this
collection been approved by the site administrator. It then submits this information to Citrix, to help improve the
product.
Citrix App Library (NT SERVICE\CitrixAppLibrary): Supports management and provisioning of AppDisks, AppDNA
integration, and management of App-V.
Citrix Broker Service (NT SERVICE\CitrixBrokerService): Selects the virtual desktops or applications that are available to
users.
Citrix Configuration Logging Service (NT SERVICE\CitrixConfigurationLogging): Records all configuration changes and
other state changes made by administrators to the site.
Citrix Configuration Service (NT SERVICE\CitrixConfigurationService): Site-wide repository for shared configuration.
Citrix Delegated Administration Service (NT SERVICE\CitrixDelegatedAdmin): Manages the permissions granted to
administrators.
Citrix Environment T est Service (NT SERVICE\CitrixEnvT est): Manages self-tests of the other Delivery Controller services.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.312
Citrix Host Service (NT SERVICE\CitrixHostService): Stores information about the hypervisor infrastructures used in a
XenApp or XenDesktop deployment, and also offers functionality used by the console to enumerate resources in a
hypervisor pool.
Citrix Machine Creation Service (NT SERVICE\CitrixMachineCreationService): Orchestrates the creation of desktop VMs.
Citrix Monitor Service (NT SERVICE\CitrixMonitor): Collects metrics for XenApp or XenDesktop, stores historical
information, and provides a query interface for troubleshooting and reporting tools.
Citrix Storefront Service (NT SERVICE\ CitrixStorefront): Supports management of StoreFront. (It is not part of the
StoreFront component itself.)
Citrix Storefront Privileged Administration Service (NT SERVICE\CitrixPrivilegedService): Supports privileged management
operations of StoreFront. (It is not part of the StoreFront component itself.)
Citrix Config Synchronizer Service (NT SERVICE\CitrixConfigSyncService): Propagates configuration data from the main
site database to the Local Host Cache.
Citrix High Availability Service (NT SERVICE\CitrixHighAvailabilityService): Selects the virtual desktops or applications that
are available to users, when the main site database is unavailable.
Delivery Controller installation also creates the following Windows services. T hese are also created when installed with
other Citrix components:
Citrix Diagnostic Facility COM Server (NT SERVICE\CdfSvc): Supports the collection of diagnostic information for use by
Citrix Support.
Citrix T elemetry Service (NT SERVICE\CitrixT elemetryService): Collects diagnostic information for analysis by Citrix, such
that the analysis results and recommendations can be viewed by administrators to help diagnose issues with the site.
Delivery Controller installation also creates the following Windows service. T his is not currently used. If it has been enabled,
disable it.
Citrix Remote Broker Provider (NT SERVICE\XaXdCloudProxy)
Delivery Controller installation also creates these following Windows services. T hese are not currently used, but must be
enabled. Do not disable them.
Citrix Orchestration Service (NT SERVICE\CitrixOrchestration)
Citrix T rust Service (NT SERVICE\CitrixT rust)
Except for the Citrix Storefront Privileged Administration Service, these services are granted the logon right Log on as a
service and the privileges Adjust memory quotas for a process, Generate security audits, and Replace a process level token.
You do not need to change these user rights. T hese privileges are not used by the Delivery Controller and are automatically
disabled.
Configure service settings
Except for the Citrix Storefront Privileged Administration service and the Citrix Telemetry Service, the Delivery Controller
Windows services listed above in the Configure user rights section are configured to log on as the NET WORK SERVICE
identity. Do not alter these service settings.
T he Citrix Storefront Privileged Administration service is configured to log on Local System (NT AUT HORIT Y\SYST EM). T his
is required for Delivery Controller StoreFront operations that are not normally available to services (including creating
Microsoft IIS sites). Do not alter its service settings.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.313
T he Citrix Telemetry Service is configured to log on as its own service-specific identity.
You can disable the Citrix Telemetry Service. Apart from this service, and services that are already disabled, do not disable
any other of these Delivery Controller Windows services.
Configure registry settings
It is no longer necessary to enable creation of 8.3 file names and folders on the VDA file system. T he registry key
Nt f sDisable8dot 3NameCreat ion can be configured to disable creation of 8.3 file names and folders. You can also
configure this using the f sut il.exe behavior set disable8dot 3 command.
Deployment scenario security implications
Your user environment can contain either user devices that are unmanaged by your organization and completely under the
control of the user, or user devices that are managed and administered by your organization. T he security considerations
for these two environments are generally different.
Managed user devices
Managed user devices are under administrative control; they are either under your own control, or the control of another
organization that you trust. You may configure and supply user devices directly to users; alternatively, you may provide
terminals on which a single desktop runs in full-screen-only mode. Follow the general security best practices described
above for all managed user devices. T his release has the advantage that minimal software is required on a user device.
A managed user device can be configured to be used in full-screen-only mode or in window mode:
Full-screen-only mode: Users log on to it with the usual Log On T o Windows screen. T he same user credentials are then
used to log on automatically to this release.
Users see their desktop in a window: Users first log on to the user device, then log on to this release through a web site
supplied with the release.
Unmanaged user devices
User devices that are not managed and administered by a trusted organization cannot be assumed to be under
administrative control. For example, you might permit users to obtain and configure their own devices, but users might not
follow the general security best practices described above. T his release has the advantage that it is possible to deliver
desktops securely to unmanaged user devices. T hese devices should still have basic antivirus protection that will defeat
keylogger and similar input attacks.
Dat a st orage considerat ions
When using this release, you can prevent users from storing data on user devices that are under their physical control.
However, you must still consider the implications of users storing data on desktops. It is not good practice for users to
store data on desktops; data should be held on file servers, database servers, or other repositories where it can be
appropriately protected.
Your desktop environment may consist of various types of desktops, such as pooled and dedicated desktops. Users should
never store data on desktops that are shared amongst users, such as pooled desktops. If users store data on dedicated
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.314
desktops, that data should be removed if the desktop is later made available to other users.
Mixed-version environment s
Mixed-version environments are inevitable during some upgrades. Follow best-practice and minimize the time that Citrix
components of different versions co-exist. In mixed-version environments, security policy, for example, may not be
uniformly enforced.
Not e: T his is typical of other software products; the use of an earlier version of Active Directory only partially enforces
Group Policy with later versions of Windows.
T he following scenario describes a security issue that can occur in a specific mixed-version Citrix environment. When Citrix
Receiver 1.7 is used to connect to a virtual desktop running the VDA in XenApp and XenDesktop 7.6 Feature Pack 2, the
policy setting Allow file t ransf er bet ween deskt op and client is enabled in the Site but cannot be disabled by a
Delivery Controller running XenApp and XenDesktop 7.1. It does not recognize the policy setting, which was released in the
later version of the product. T his policy setting allows users to upload and download files to their virtual desktop, which is
the security issue. To work around this, upgrade the Delivery Controller (or a standalone instance of Studio) to version 7.6
Feature Pack 2 and then use Group Policy to disable the policy setting. Alternatively, use local policy on all affected virtual
desktops.
Remote PC Access security considerations
Remote PC Access implements the following security features:
Smart card use is supported.
When a remote session connects, the office PC's monitor appears as blank.
Remote PC Access redirects all keyboard and mouse input to the remote session, except CT RL+ALT +DEL and USBenabled smart cards and biometric devices.
SmoothRoaming is supported for a single user only.
When a user has a remote session connected to an office PC, only that user can resume local access of the office PC.
T o resume local access, the user presses Ctrl-Alt-Del on the local PC and then logs on with the same credentials used by
the remote session. T he user can also resume local access by inserting a smart card or leveraging biometrics, if your
system has appropriate third-party Credential Provider integration. T his default behavior can be overridden by enabling
Fast User Switching via Group Policy Objects (GPOs) or by editing the registry.
Not e: Citrix recommends that you do not assign VDA administrator privileges to general session users.
Aut omat ic assignment s
By default, Remote PC Access supports automatic assignment of multiple users to a VDA. In XenDesktop 5.6 Feature Pack
1, administrators could override this behavior using the RemotePCAccess.ps1 PowerShell script. T his release uses a registry
entry to allow or prohibit multiple automatic remote PC assignments; this setting applies to the entire Site.
Caut ion: 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 Registry Editor can be solved. Use Registry Editor
at your own risk. Be sure to back up the registry before you edit it.
To restrict automatic assignments to a single user:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.315
On each Controller in the Site, set the following registry entry:
HKEY_LOCAL_MACHINE\Software\Citrix|DesktopServer
Name: AllowMultipleRemotePCAssignments
Type: REG_DWORD
Data: 0 = Disable multiple user assignment, 1 = (Default) Enable multiple user assignment.
If there are any existing user assignments, remove them using SDK commands for the VDA to subsequently be eligible for a
single automatic assignment.
Remove all assigned users from the VDA: $machine.AssociatedUserNames | %{ Remove-BrokerUser-Name $_ -Machine
$machine
Remove the VDA from the Delivery Group: $machine | Remove-BrokerMachine -DesktopGroup $desktopGroup
Restart the physical office PC.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.316
Integrate XenApp and XenDesktop with NetScaler
Gateway
Nov 28 , 20 17
StoreFront servers are deployed and configured to manage access to published resources and data. For remote access,
adding NetScaler Gateway in front of StoreFront is recommended.
Note
For detailed configuration steps on how to integrate XenApp and XenDesktop with NetScaler Gateway, see the StoreFront
documentation.
T he following diagram illustrates an example of a Citrix simplified Citrix deployment that includes NetScaler Gateway.
NetScaler Gateway communicates with StoreFront to protect apps and data delivered by XenApp and XenDesktop. T he
user devices run Citrix Receiver to create a secure connection and access their apps, desktops, and files.
Users log on and authenticate using NetScaler Gateway. NetScaler Gateway is deployed and secured in the DMZ. Twofactor authentication is configured. Based on the user credentials, users are provided with the relevant resources and
applications. Applications and data are on appropriate servers (not shown on the diagram). Separate servers used for
security sensitive applications and data.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.317
Delegated Administration
Nov 28 , 20 17
T he Delegated Administration model offers the flexibility to match how your organization wants to delegate
administration activities, using role and object-based control. Delegated Administration accommodates deployments of all
sizes, and allows you to configure more permission granularity as your deployment grows in complexity. Delegated
Administration uses three concepts: administrators, roles, and scopes.
Administ rat ors — An administrator represents an individual person or a group of people identified by their Active
Directory account. Each administrator is associated with one or more role and scope pairs.
Roles — A role represents a job function, and has defined permissions associated with it. For example, the Delivery
Group Administrator role has permissions such as 'Create Delivery Group' and 'Remove Desktop from Delivery Group.' An
administrator can have multiple roles for a Site, so a person could be a Delivery Group Administrator and a Machine
Catalog Administrator. Roles can be built-in or custom.
T he built-in roles are:
Role
P ermissions
Full
Can perform all tasks and operations. A Full Administrator is always combined with the All scope.
Administrator
Read Only
Can see all objects in specified scopes as well as global information, but cannot change anything. For
Administrator
example, a Read Only Administrator with Scope=London can see all global objects (such as
Configuration Logging) and any London-scoped objects (for example, London Delivery Groups).
However, that administrator cannot see objects in the New York scope (assuming that the London
and New York scopes do not overlap).
Help Desk
Can view Delivery Groups, and manage the sessions and machines associated with those groups. Can
Administrator
see the Machine Catalog and host information for the Delivery Groups being monitored, and can
also perform session management and machine power management operations for the machines in
those Delivery Groups.
Machine
Can create and manage Machine Catalogs and provision the machines into them. Can build Machine
Catalog
Catalogs from the virtualization infrastructure, Provisioning Services, and physical machines. T his role
Administrator
can manage base images and install software, but cannot assign applications or desktops to users.
Delivery
Can deliver applications, desktops, and machines; can also manage the associated sessions. Can also
Group
manage application and desktop configurations such as policies and power management settings.
Administrator
Host
Can manage host connections and their associated resource settings. Cannot deliver machines,
Administrator
applications, or desktops to users.
In certain product editions, you can create custom roles to match the requirements of your organization, and delegate
permissions with more detail. You can use custom roles to allocate permissions at the granularity of an action or task in a
console.
Scopes — A scope represents a collection of objects. Scopes are used to group objects in a way that is relevant to your
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.318
organization (for example, the set of Delivery Groups used by the Sales team). Objects can be in more than one scope;
you can think of objects being labeled with one or more scopes. T here is one built-in scope: 'All,' which contains all
objects. T he Full Administrator role is always paired with the All scope.
Company XYZ decided to manage applications and desktops based on their department (Accounts, Sales, and Warehouse)
and their desktop operating system (Windows 7 or Windows 8). T he administrator created five scopes, then labeled each
Delivery Group with two scopes: one for the department where they are used and one for the operating system they use.
T he following administrators were created:
Administ rat or
Roles
Scopes
domain/fred
Full Administrator
All (the Full Administrator role always has the All scope)
domain/rob
Read Only Administrator
All
domain/heidi
Read Only Administrator
All
Help Desk Administrator
Sales
domain/warehouseadmin
Help Desk Administrator
Warehouse
domain/peter
Delivery Group Administrator
Win7
Machine Catalog Administrator
Fred is a Full Administrator and can view, edit, and delete all objects in the system.
Rob can view all objects in the Site but cannot edit or delete them.
Heidi can view all objects and can perform help desk tasks on Delivery Groups in the Sales scope. T his allows her to
manage the sessions and machines associated with those groups; she cannot make changes to the Delivery Group, such
as adding or removing machines.
Anyone who is a member of the warehouseadmin Active Directory security group can view and perform help desk tasks
on machines in the Warehouse scope.
Peter is a Windows 7 specialist and can manage all Windows 7 Machine Catalogs and can deliver Windows 7
applications, desktops, and machines, regardless of which department scope they are in. T he administrator considered
making Peter a Full Administrator for the Win7 scope; however, she decided against this, because a Full Administrator
also has full rights over all objects that are not scoped, such as 'Site' and 'Administrator.'
Generally, the number of administrators and the granularity of their permissions depends on the size and complexity of the
deployment.
In small or proof-of-concept deployments, one or a few administrators do everything; there is no delegation. In this case,
create each administrator with the built-in Full Administrator role, which has the All scope.
In larger deployments with more machines, applications, and desktops, more delegation is needed. Several administrators
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.319
might have more specific functional responsibilities (roles). For example, two are Full Administrators, and others are Help
Desk Administrators. Additionally, an administrator might manage only certain groups of objects (scopes), such as
machine catalogs. In this case, create new scopes, plus administrators with one of the built-in roles and the appropriate
scopes.
Even larger deployments might require more (or more specific) scopes, plus different administrators with unconventional
roles. In this case, edit or create additional scopes, create custom roles, and create each administrator with a built-in or
custom role, plus existing and new scopes.
For flexibility and ease of configuration, you can create new scopes when you create an administrator. You can also specify
scopes when creating or editing Machine Catalogs or connections.
When you create a Site as a local administrator, your user account automatically becomes a Full Administrator with full
permissions over all objects. After a Site is created, local administrators have no special privileges.
T he Full Administrator role always has the All scope; you cannot change this.
By default, an administrator is enabled. Disabling an administrator might be necessary if you are creating the new
administrator now, but that person will not begin administration duties until later. For existing enabled administrators, you
might want to disable several of them while you are reorganizing your object/scopes, then re-enable them when you are
ready to go live with the updated configuration. You cannot disable a Full Administrator if it will result in there being no
enabled Full Administrator. T he enable/disable check box is available when you create, copy, or edit an administrator.
When you delete a role/scope pair while copying, editing, or deleting an administrator, it deletes only the relationship
between the role and the scope for that administrator; it does not delete either the role or the scope, nor does it affect
any other administrator who is configured with that role/scope pair.
T o manage administrators, click Configuration > Administrators in the Studio navigation pane, and then click the
Administrators tab in the upper middle pane.
T o create an administrator, click Create new Administrator in the Actions pane. T ype or browse to the user account
name, select or create a scope, and select a role. T he new administrator is enabled by default; you can change this.
T o copy an administrator, select the administrator in the middle pane and then click Copy Administrator in the Actions
pane. T ype or browse to the user account name. You can select and then edit or delete any of the role/scope pairs, and
add new ones. T he new administrator is enabled by default; you can change this.
T o edit an administrator, select the administrator in the middle pane and then click Edit Administrator in the Actions
pane. You can edit or delete any of the role/scope pairs, and add new ones.
T o delete an administrator, select the administrator in the middle pane and then click Delete Administrator in the Actions
pane. You cannot delete a Full Administrator if it will result in there being no enabled Full Administrator.
Role names can contain up to 64 Unicode characters; they cannot contain the following characters: \ (backslash), /
(forward slash), ; (semicolon), : (colon), # (pound sign) , (comma), * (asterisk), ? (question mark), = (equal sign), < (left arrow), >
(right arrow), | (pipe), [ ] (left or right bracket), ( ) (left or right parenthesis), " (quotation marks), and ' (apostrophe).
Descriptions can contain up to 256 Unicode characters.
You cannot edit or delete a built-in role. You cannot delete a custom role if any administrator is using it.
Note: Only certain product editions support custom roles. Editions that do not support custom roles do not have related
entries in the Actions pane.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.320
T o manage roles, click Configuration > Administrators in the Studio navigation pane, and then click the Roles tab in the
upper middle pane.
T o view role details, select the role in the middle pane. T he lower portion of the middle pane lists the object types and
associated permissions for the role. Click the Administrators tab in the lower pane to display a list of administrators who
currently have this role.
T o create a custom role, click Create new Role in the Actions pane. Enter a name and description. Select the object
types and permissions.
T o copy a role, select the role in the middle pane and then click Copy Role in the Actions pane. Change the name,
description, object types, and permissions, as needed.
T o edit a custom role, select the role in the middle pane and then click Edit Role in the Actions pane. Change the name,
description, object types, and permissions, as needed.
T o delete a custom role, select the role in the middle pane and then click Delete Role in the Actions pane. When
prompted, confirm the deletion.
When you create a Site, the only available scope is the 'All' scope, which cannot be deleted.
You can create scopes using the procedure below. You can also create scopes when you create an administrator; each
administrator must be associated with at least one role and scope pair. When you are creating or editing desktops, machine
catalogs, applications, or hosts, you can add them to an existing scope; if you do not add them to a scope, they remain part
of the 'All' scope.
Site creation cannot be scoped, nor can Delegated Administration objects (scopes and roles). However, objects you cannot
scope are included in the 'All' scope. (Full Administrators always have the All scope.) Machines, power actions, desktops, and
sessions are not directly scoped; administrators can be allocated permissions over these objects through the associated
machine catalogs or Delivery Groups.
Scope names can contain up to 64 Unicode characters; they cannot include the following characters: \ (backslash), /
(forward slash), ; (semicolon), : (colon), # (pound sign) , (comma), * (asterisk), ? (question mark), = (equal sign), < (left arrow), >
(right arrow), | (pipe), [ ] (left or right bracket), ( ) (left or right parenthesis), " (quotation marks), and ' (apostrophe).
Descriptions can contain up to 256 Unicode characters.
When you copy or edit a scope, keep in mind that removing objects from the scope can make those objects inaccessible to
the administrator. If the edited scope is paired with one or more roles, ensure that the scope updates you make do not
make any role/scope pair unusable.
T o manage scopes, click Configuration > Administrators in the Studio navigation pane, and then click the Scopes tab in the
upper middle pane.
T o create a scope, click Create new Scope in the Actions pane. Enter a name and description. T o include all objects of a
particular type (for example, Delivery Groups), select the object type. T o include specific objects, expand the type and
then select individual objects (for example, Delivery Groups used by the Sales team).
T o copy a scope, select the scope in the middle pane and then click Copy Scope in the Actions pane. Enter a name and
description. Change the object types and objects, as needed.
T o edit a scope, select the scope in the middle pane and then click Edit Scope in the Actions pane. Change the name,
description, object types, and objects, as needed.
T o delete a scope, select the scope in the middle pane and then click Delete Scope in the Actions pane. When prompted,
confirm the deletion.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.321
You can create two types of Delegated Administration reports:
An HT ML report that lists the role/scope pairs associated with an administrator, plus the individual permissions for each
type of object (for example, Delivery Groups and Machine Catalogs). You generate this report from Studio.
To create this report, click Configuration > Administrators in the navigation pane. Select an administrator in the middle
pane and then click Create Report in the Actions pane.
You can also request this report when creating, copying, or editing an administrator.
An HT ML or CSV report that maps all built-in and custom roles to permissions. You generate this report by running a
PowerShell script named OutputPermissionMapping.ps1.
To run this script, you must be a Full Administrator, a Read Only Administrator, or a custom administrator with permission
to read roles. T he script is located in: Program
Files\Citrix\DelegatedAdmin\SnapIn\Citrix.DelegatedAdmin.Admin.V1\Scripts\.
Syntax:
OutputPermissionMapping.ps1 [-Help] [-Csv] [-Path <string>] [-AdminAddress <string>] [-Show] [<CommonParameters>]
P aramet er
Descript ion
-Help
Displays script help.
-Csv
Specifies CSV output. Default = HT ML
-Path <string>
Where to write the output. Default = stdout
-AdminAddress
IP address or host name of the Delivery Controller to connect to. Default = localhost
<string>
-Show
(Valid only when the -Path parameter is also specified) When you write the output to a file,
-Show causes the output to be opened in an appropriate program, such as a web browser.
<CommonParameters>
Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer,
and OutVariable. For details, see the Microsoft documentation.
T he following example writes an HT ML table to a file named Roles.html and opens the table in a web browser.
& "$env:ProgramFiles\Citrix\DelegatedAdmin\SnapIn\
Citrix.DelegatedAdmin.Admin.V1\Scripts\OutputPermissionMapping.ps1"
-Path Roles.html –Show
T he following example writes a CSV table to a file named Roles.csv. T he table is not displayed.
& "$env:ProgramFiles\Citrix\DelegatedAdmin\SnapIn\
Citrix.DelegatedAdmin.Admin.V1\Scripts\OutputPermissionMapping.ps1"
–CSV -Path Roles.csv
From a Windows command prompt, the preceding example command is:
powershell -command "& '%ProgramFiles%\Citrix\DelegatedAdmin\SnapIn\
Citrix.DelegatedAdmin.Admin.V1\Scripts\OutputPermissionMapping.ps1'
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.322
-CSV -Path Roles.csv"
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.323
Smart cards
Nov 28 , 20 17
Smart cards and equivalent technologies are supported within the guidelines described in this article. To use smart cards
with XenApp or XenDesktop:
Understand your organization’s security policy concerning the use of smart cards. T hese policies might, for example,
state how smart cards are issued and how users should safeguard them. Some aspects of these policies might need to
be reassessed in a XenApp or XenDesktop environment.
Determine which user device types, operating systems, and published applications are to be used with smart cards.
Familiarize yourself with smart card technology and your selected smart card vendor hardware and software.
Know how to deploy digital certificates in a distributed environment.
Types of smart cards
Enterprise and consumer smart cards have the same dimensions, electrical connectors, and fit the same smart card readers.
Smart cards for enterprise use contain digital certificates. T hese smart cards support Windows logon, and can also be used
with applications for digital signing and encryption of documents and e-mail. XenApp and XenDesktop support these uses.
Smart cards for consumer use do not contain digital certificates; they contain a shared secret. T hese smart cards can
support payments (such as a chip-and-signature or chip-and-PIN credit card). T hey do not support Windows logon or typical
Windows applications. Specialized Windows applications and a suitable software infrastructure (including, for example, a
connection to a payment card network) are needed for use with these smart cards. Contact your Citrix representative for
information on supporting these specialized applications on XenApp or XenDesktop.
For enterprise smart cards, there are compatible equivalents that can be used in a similar way.
A smart card-equivalent USB token connects directly to a USB port. T hese USB tokens are usually the size of a USB flash
drive, but can be as small as a SIM card used in a mobile phone. T hey appear as the combination of a smart card plus a
USB smart card reader.
A virtual smart card using a Windows T rusted Platform Module (T PM) appears as a smart card. T hese virtual smart cards
are supported for Windows 8 and Windows 10, using Citrix Receiver minimum 4.3.
Versions of XenApp and XenDesktop earlier than 7.6 FP3 do not support virtual smart cards.
For more information on virtual smart cards, see Virtual Smart Card Overview.
Not e: T he term “virtual smart card” is also used to describe a digital certificate simply stored on the user computer.
T hese digital certificates are not strictly equivalent to smart cards.
XenApp and XenDesktop smart card support is based on the Microsoft Personal Computer/Smart Card (PC/SC) standard
specifications. A minimum requirement is that smart cards and smart card devices must be supported by the underlying
Windows operating system and must be approved by the Microsoft Windows Hardware Quality Labs (WHQL) to be used
on computers running qualifying Windows operating systems. See the Microsoft documentation for additional information
about hardware PC/SC compliance. Other types of user devices may comply with the PS/SC standard. For more
information, refer to the Citrix Ready program at http://www.citrix.com/ready/.
Usually, a separate device driver is needed for each vendor’s smart card or equivalent. However, if smart cards conform to a
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.324
standard such as the NIST Personal Identity Verification (PIV) standard, it may be possible to use a single device driver for a
range of smart cards. T he device driver must be installed on both the user device and the Virtual Delivery Agent (VDA). T he
device driver is often supplied as part of a smart card middleware package available from a Citrix partner; the smart card
middleware package will offer advanced features. T he device driver may also be described as a Cryptographic Service
Provider (CSP), Key Storage Provider (KSP), or minidriver.
T he following smart card and middleware combinations for Windows systems have been tested by Citrix as representative
examples of their type. However, other smart cards and middleware can also be used. For more information about Citrixcompatible smart cards and middleware, see http://www.citrix.com/ready.
Middleware
Mat ching cards
ActivClient 7.0 (DoD mode enabled)
DoD CAC card
ActivClient 7.0 in PIV mode
NIST PIV card
Microsoft mini driver
NIST PIV card
GemAlto Mini Driver for .NET card
GemAlto .NET v2+
Microsoft native driver
Virtual Smart Cards (T PM)
For information about smart card usage with other types of devices, see the Citrix Receiver documentation for that device.
For more information about PIV usage with XenDesktop, see Configuring Citrix XenDesktop 7.6 and NetScaler Gateway
10.5 with PIV Smart Card Authentication.
For information about smart card usage with other types of devices, see the Citrix Receiver documentation for that device.
Smart cards are supported only for remote access to physical office PCs running Windows 10, Windows 8 or Windows 7;
smart cards are not supported for office PCs running Windows XP.
T he following smart cards were tested with Remote PC Access:
Middleware
Mat ching cards
Gemalto .NET minidriver
Gemalto .NET v2+
ActivIdentity ActivClient 6.2
NIST PIV
ActivIdentity ActivClient 6.2
CAC
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.325
Microsoft minidriver
NIST PIV
Microsoft native driver
Virtual smart cards
Types of smart card readers
A smart card reader may be built in to the user device, or be separately attached to the user device (usually via USB or
Bluetooth). Contact card readers that comply with the USB Chip/Smart Card Interface Devices (CCID) specification are
supported. T hey contain a slot or swipe into which the user inserts the smart card. T he Deutsche Kreditwirtschaft
(DK) standard defines four classes of contact card readers.
Class 1 smart card readers are the most common, and usually just contain a slot. Class 1 smart card readers are supported,
usually with a standard CCID device driver supplied with the operating system.
Class 2 smart card readers also contain a secure keypad that cannot be accessed by the user device. Class 2 smart card
readers may be built into a keyboard with an integrated secure keypad. For class 2 smart card readers, contact your Citrix
representative; a reader-specific device driver may be required to enable the secure keypad capability.
Class 3 smart card readers also contain a secure display. Class 3 smart card readers are not supported.
Class 4 smart card readers also contain a secure transaction module. Class 4 smart card readers are not supported.
Not e: T he smart card reader class is unrelated to the USB device class.
Smart card readers must be installed with a corresponding device driver on the user device.
For information about supported smart card readers, see the documentation for the Citrix Receiver you are using. In the
Citrix Receiver documentation, supported versions are usually listed in a smart card article or in the system requirements
article.
User experience
Smart card support is integrated into XenApp and XenDesktop, using a specific ICA/HDX smart card virtual channel that is
enabled by default.
Important: Do not use generic USB redirection for smart card readers. T his is disabled by default for smart card readers, and
is not supported if enabled.
Multiple smart cards and multiple readers can be used on the same user device, but if pass-through authentication is in use,
only one smart card must be inserted when the user starts a virtual desktop or application. When a smart card is used within
an application (for example, for digital signing or encryption functions), there might be additional prompts to insert a smart
card or enter a PIN. T his can occur if more than one smart card has been inserted at the same time.
If users are prompted to insert a smart card when the smart card is already in the reader, they should select Cancel.
If users are prompted for the PIN, they should enter the PIN again.
If you are using hosted applications running on Windows Server 2008 or 2008 R2 and with smart cards requiring the
Microsoft Base Smart Card Cryptographic Service Provider, you might find that if a user runs a smart card transaction, all
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.326
other users who use a smart card in the logon process are blocked. For further details and a hotfix for this issue,
see http://support.microsoft.com/kb/949538.
You can reset PINs using a card management system or vendor utility.
Important
Within a XenApp or XenDesktop session, using a smart card with the Microsoft Remote Desktop Connection application is not
supported. T his is sometimes described as a "double hop" use.
Before deploying smart cards
Obtain a device driver for the smart card reader and install it on the user device. Many smart card readers can use the
CCID device driver supplied by Microsoft.
Obtain a device driver and cryptographic service provider (CSP) software from your smart card vendor, and install them on
both user devices and virtual desktops. T he driver and CSP software must be compatible with XenApp and XenDesktop;
check the vendor documentation for compatibility. For virtual desktops using smart cards that support and use the
minidriver model, smart card minidrivers should download automatically, but you can obtain them
from http://catalog.update.microsoft.com or from your vendor. Additionally, if PKCS#11 middleware is required, obtain it
from the card vendor.
Important: Citrix recommends that you install and test the drivers and CSP software on a physical computer before
installing Citrix software.
Add the Citrix Receiver for Web URL to the T rusted Sites list for users who work with smart cards in Internet Explorer
with Windows 10. In Windows 10, Internet Explorer does not run in protected mode by default for trusted sites.
Ensure that your public key infrastructure (PKI) is configured appropriately. T his includes ensuring that certificate-toaccount mapping is correctly configured for Active Directory environment and that user certificate validation can be
performed successfully.
Ensure your deployment meets the system requirements of the other Citrix components used with smart cards, including
Citrix Receiver and StoreFront.
Ensure access to the following servers in your Site:
T he Active Directory domain controller for the user account that is associated with a logon certificate on the smart
card
Delivery Controller
Citrix StoreFront
Citrix NetScaler Gateway/Citrix Access Gateway 10.x
VDA
(Optional for Remote PC Access): Microsoft Exchange Server
Enable smart card use
St ep 1. Issue smart cards to users according to your card issuance policy.
St ep 2. (Optional) Set up the smart cards to enable users for Remote PC Access.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.327
St ep 3. Install and configure the Delivery Controller and StoreFront (if not already installed) for smart card remoting.
St ep 4 . Enable StoreFront for smart card use. For details, see Configure smart card authentication in
the StoreFront documentation.
St ep 5. Enable NetScaler Gateway/Access Gateway for smart card use. For details, see Configuring Authentication and
Authorization and Configuring Smart Card Access with the Web Interface in the NetScaler documentation.
St ep 6. Enable VDAs for smart card use.
Ensure the VDA has the required applications and updates.
Install the middleware.
Set up smart card remoting, enabling the communication of smart card data between Citrix Receiver on a user device
and a virtual desktop session.
St ep 7 . Enable user devices (including domain-joined or non-domain-joined machines) for smart card use. See Configure
smart card authentication in the StoreFront documentation for details.
Import the certificate authority root certificate and the issuing certificate authority certificate into the
device's keystore.
Install your vendor's smart card middleware.
Install and configure Citrix Receiver for Windows, being sure to import icaclient.adm using the Group Policy Management
Console and enable smart card authentication.
St ep 8. Test the deployment. Ensure that the deployment is configured correctly by launching a virtual desktop with a test
user's smart card. Test all possible access mechanisms (for example, accessing the desktop through Internet Explorer and
Citrix Receiver).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.328
Smart card deployments
Nov 28 , 20 17
T he following types of smart card deployments are supported by this product version and by mixed environments
containing this version. Other configurations might work but are not supported.
T ype
St oreF ront connect ivit y
Local domain-joined computers
Directly connected
Remote access from domain-joined computers
Connected through NetScaler
Gateway
Non-domain-joined computers
Directly connected
Remote access from non-domain-joined computers
Connected through NetScaler
Gateway
Non-domain-joined computers and thin clients accessing the Desktop Appliance
site
Connected through Desktop
Appliance sites
Domain-joined computers and thin clients accessing StoreFront through the
XenApp Services URL
Connected through XenApp
Services URLs
T he deployment types are defined by the characteristics of the user device to which the smart card reader is connected:
Whether the device is domain-joined or non-domain-joined.
How the device is connected to StoreFront.
What software is used to view virtual desktops and applications.
In addition, smart card-enabled applications such as Microsoft Word, and Microsoft Excel can be used in these
deployments. T hose applications allow users to digitally sign or encrypt documents.
Where possible in each of these deployments, Receiver supports bimodal authentication by offering the user a choice
between using a smart card and entering their user name and password. T his is useful if the smart card cannot be used (for
example, the user has left it at home or the logon certificate has expired).
Because users of non-domain-joined devices log on to Receiver for Windows directly, you can enable users to fall back to
explicit authentication. If you configure bimodal authentication, users are initially prompted to log on using their smart
cards and PINs but have the option to select explicit authentication if they experience any issues with their smart cards.
If you deploy NetScaler Gateway, users log on to their devices and are prompted by Receiver for Windows to authenticate
to NetScaler Gateway. T his applies to both domain-joined and non-domain-joined devices. Users can log on to NetScaler
Gateway using either their smart cards and PINs, or with explicit credentials. T his enables you to provide users with bimodal
authentication for NetScaler Gateway logons. Configure pass-through authentication from NetScaler Gateway to
StoreFront and delegate credential validation to NetScaler Gateway for smart card users so that users are silently
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.329
authenticated to StoreFront.
In a Citrix environment, smart cards are supported within a single forest. Smart card logons across forests require a direct
two-way forest trust to all user accounts. More complex multi-forest deployments involving smart cards (that is, where
trusts are only one-way or of different types) are not supported.
You can use smart cards in a Citrix environment that includes remote desktops. T his feature can be installed locally (on the
user device that the smart card is connected to) or remotely (on the remote desktop that the user device connects to).
T he smart card removal policy set on the product determines what happens if you remove the smart card from the reader
during a session. T he smart card removal policy is configured through and handled by the Windows operating system.
P olicy set t ing
Deskt op behavior
No action
No action.
Lock workstation
T he desktop session is disconnected and the virtual desktop is locked.
Force logoff
T he user is forced to log off. If the network connection is lost and this setting is
enabled, the session may be logged off and the user may lose data.
Disconnect if a remote
T he session is disconnected and the virtual desktop is locked.
Terminal Services session
If certificate revocation checking is enabled and a user inserts a smart card with an invalid certificate into a card reader, the
user cannot authenticate or access the desktop or application related to the certificate. For example, if the invalid
certificate is used for email decryption, the email remains encrypted. If other certificates on the card, such as ones used for
authentication, are still valid, those functions remain active.
T his deployment involves domain-joined user devices that run the Desktop Viewer and connect directly to StoreFront.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.330
A user logs on to a device using a smart card and PIN. Receiver authenticates the user to a Storefront server using
Integrated Windows Authentication (IWA). StoreFront passes the user security identifiers (SIDs) to XenApp or XenDesktop.
When the user starts a virtual desktop or application, the user is not prompted for a PIN again because the single sign-on
feature is configured on Receiver.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
T his deployment involves domain-joined user devices that run the Desktop Viewer and connect to StoreFront through
NetScaler Gateway/Access Gateway.
A user logs on to a device using a smart card and PIN, and then logs on again to NetScaler Gateway/Access Gateway. T his
second logon can be with either the smart card and PIN or a user name and password because Receiver allows bimodal
authentication in this deployment.
T he user is automatically logged on to StoreFront, which passes the user security identifiers (SIDs) to XenApp or
XenDesktop. When the user starts a virtual desktop or application, the user is not prompted again for a PIN because the
single sign-on feature is configured on Receiver.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.331
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
T his deployment involves non-domain-joined user devices that run the Desktop Viewer and connect directly to StoreFront.
A user logs on to a device. Typically, the user enters a user name and password but, since the device is not joined to a
domain, credentials for this logon are optional. Because bimodal authentication is possible in this deployment, Receiver
prompts the user either for a smart card and PIN or a user name and password. Receiver then authenticates to Storefront.
StoreFront passes the user security identifiers (SIDs) to XenApp or XenDesktop. When the user starts a virtual desktop or
application, the user is prompted for a PIN again because the single sign-on feature is not available in this deployment.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
T his deployment involves non-domain-joined user devices that run the Desktop Viewer and connect directly to StoreFront.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.332
A user logs on to a device. Typically, the user enters a user name and password but, since the device is not joined to a
domain, credentials for this logon are optional. Because bimodal authentication is possible in this deployment, Receiver
prompts the user either for a smart card and PIN or a user name and password. Receiver then authenticates to Storefront.
StoreFront passes the user security identifiers (SIDs) to XenApp or XenDesktop. When the user starts a virtual desktop or
application, the user is prompted for a PIN again because the single sign-on feature is not available in this deployment.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
T his deployment involves non-domain-joined user devices that may run the Desktop Lock and connect to StoreFront
through Desktop Appliance sites.
T he Desktop Lock is a separate component that is released with XenApp, XenDesktop, and VDI-in-a-Box. It is an
alternative to the Desktop Viewer and is designed mainly for repurposed Windows computers and Windows thin clients.
T he Desktop Lock replaces the Windows shell and Task Manager in these user devices, preventing users from accessing the
underlying devices. With the Desktop Lock, users can access Windows Server Machine desktops and Windows Desktop
Machine desktops. Installation of Desktop Lock is optional.
A user logs on to a device with a smart card. If Desktop Lock is running on the device, the device is configured to launch a
Desktop Appliance site through Internet Explorer running in Kiosk Mode. An ActiveX control on the site prompts the user
for a PIN, and sends it to StoreFront. StoreFront passes the user security identifiers (SIDs) to XenApp or XenDesktop. T he
first available desktop in the alphabetical list in an assigned Desktop Group starts.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
T his deployment involves domain-joined user devices that run the Desktop Lock and connect to StoreFront through
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.333
XenApp Services URLs.
T he Desktop Lock is a separate component that is released with XenApp, XenDesktop, and VDI-in-a-Box. It is an
alternative to the Desktop Viewer and is designed mainly for repurposed Windows computers and Windows thin clients.
T he Desktop Lock replaces the Windows shell and Task Manager in these user devices, preventing users from accessing the
underlying devices. With the Desktop Lock, users can access Windows Server Machine desktops and Windows Desktop
Machine desktops. Installation of Desktop Lock is optional.
A user logs on to a device using a smart card and PIN. If Desktop Lock is running on the device, it authenticates the user to
a Storefront server using Integrated Windows Authentication (IWA). StoreFront passes the user security identifiers (SIDs) to
XenApp or XenDesktop. When the user starts a virtual desktop, the user is not prompted for a PIN again because the single
sign-on feature is configured on Receiver.
T his deployment can be extended to a double-hop with the addition of a second StoreFront server and a server hosting
applications. A Receiver from the virtual desktop authenticates to the second StoreFront server. Any authentication
method can be used for this second connection. T he configuration shown for the first hop can be reused in the second
hop or used in the second hop only.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.334
Pass-through authentication and single sign-on with
smart cards
Nov 28 , 20 17
Pass-through authentication with smart cards to virtual desktops is supported on user devices running Windows 10,
Windows 8, and Windows 7 SP1 Enterprise and Professional Editions.
Pass-through authentication with smart cards to hosted applications is supported on servers running Windows Server 2016,
Windows Server 2012 R2, Windows Server 2012, and Windows Server 2008 R2 SP1.
To use pass-through authentication with smart cards hosted applications, ensure you enable the use of Kerberos when you
configure Pass-through with smartcard as the authentication method for the site.
Note: T he availability of pass-through authentication with smart cards depends on many factors including, but not limited
to:
Your organization's security policies regarding pass-through authentication.
Middleware type and configuration.
Smart card reader types.
Middleware PIN caching policy.
Pass-through authentication with smart cards is configured on Citrix StoreFront. See the StoreFront documentation for
details.
Single sign-on is a Citrix feature that implements pass-through authentication with virtual desktop and application
launches. You can use this feature in domain-joined, direct-to-StoreFront and domain-joined, NetScaler-to-StoreFront
smart card deployments to reduce the number of times that users enter their PIN. To use single sign-on in these
deployment types, edit the following parameters in the default.ica file, which is located on the StoreFront server:
Domain-joined, direct-to-StoreFront smart card deployments — Set DisableCtrlAltDel to Off
Domain-joined, NetScaler-to-StoreFront smart card deployments — Set UseLocalUserAndPassword to On
For more instructions on setting these parameters, see the StoreFront or NetScaler Gateway documentation.
T he availability of single sign-on functionality depends on many factors including, but not limited to:
Your organization's security policies regarding single sign-on.
Middleware type and configuration.
Smart card reader types.
Middleware PIN caching policy.
Note: When the user logs on to the Virtual Delivery Agent (VDA) on a machine with an attached smart card reader, a
Windows tile may appear representing the previous successful mode of authentication, such as smart card or password. As
a result, when single sign-on is enabled, the single sign-on tile may appear. T o log on, the user must select Switch Users to
select another tile because the single sign-on tile will not work.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.335
Transport Layer Security (TLS)
Jan 0 4 , 20 18
XenApp and XenDesktop support the T ransport Layer Security (T LS) protocol for T CP-based connections between
components. XenApp and XenDesktop also support the Datagram T ransport Layer Security (DT LS) protocol for UDP-based
ICA/HDX connections, using adaptive transport.
T LS and DT LS are similar, and support the same digital certificates. Configuring a XenApp or XenDesktop Site to use T LS
also configures it to use DT LS. Use the following procedures; the steps are common to both T LS and DT LS except where
noted:
Obtain, install, and register a server certificate on all Delivery Controllers, and configure a port with the T LS certificate.
For details, see Install T LS server certificates on Controllers.
Optionally, you can change the ports the Controller uses to listen for HT T P and HT T PS traffic.
Enable T LS connections between Citrix Receivers and Virtual Delivery Agents (VDAs) by completing the following tasks:
Configure T LS on the machines where the VDAs are installed. (For convenience, further references to machines where
VDAs are installed are simply called "VDAs.") For general information, see about T LS settings on VDAs. It is highly
recommended that you use the Citrix supplied PowerShell script to configure T LS/DT LS. For details, see Configure T LS
on a VDA using the PowerShell script. However, if you want to configure T LS/DT LS manually, see Manually configure
T LS on a VDA.
Configure T LS in the Delivery Groups containing the VDAs by running a set of PowerShell cmdlets in Studio. For
details, see Configure T LS on Delivery Groups.
Requirements and considerations:
Enabling T LS connections between users and VDAs is valid only for XenApp 7.6 and XenDesktop 7.6 Sites, plus later
supported releases.
Configure T LS in the Delivery Groups and on the VDAs after you install components, create a Site, create machine
catalogs, and create Delivery Groups.
T o configure T LS in the Delivery Groups, you must have permission to change Controller access rules. A Full
Administrator has this permission.
T o configure T LS on the VDAs, you must be a Windows administrator on the machine where the VDA is installed.
On pooled VDAs that are provisioned by Machine Creation Services or Provisioning Services, the VDA machine
image is reset on restart, causing previous T LS settings to be lost. Run the PowerShell script each time the VDA is
restarted to reconfigure the T LS settings.
Warning
For tasks that include working in the Windows registry—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 Registry Editor can
be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.
For information about enabling T LS to the Site database, see CT X137556.
Install TLS server certificates on Controllers
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.336
For HT T PS, the XML Service supports T LS features by using server certificates, not client certificates. To obtain, install, and
register a certificate on a Controller, and to configure a port with the T LS certificate:
If the Controller has IIS installed, follow the guidance in https://technet.microsoft.com/enus/library/cc771438%28v=ws.10%29.aspx.
If the Controller does not have IIS installed, one method of configuring the certificate is:
1. Obtain a T LS server certificate and install it on the Controller using the guidance
in http://blogs.technet.com/b/pki/archive/2009/08/05/how-to-create-a-web-server-ssl-certificate-manually.aspx. For
information on the certreq tool, see http://technet.microsoft.com/en-us/library/cc736326(WS.10).aspx.
2. Configure a port with the certificate; see http://msdn.microsoft.com/en-us/library/ms733791%28v=vs.110%29.aspx.
If the Controller is installed on Windows Server 2016, and StoreFront is installed on Windows Server 2012, a configuration
change is needed at the Controller, to change the order of T LS cipher suites.
Note
T his configuration change is not needed for Controller and StoreFront with other combinations of Windows Server versions.
T he cipher suite order list must include the T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA384, or
T LS_ECDHE_RSA_WIT H_AES_128_CBC_SHA256 cipher suites (or both); and these cipher suites must precede any
T LS_DHE_ cipher suites.
Note
Windows Server 2012 does not support the GCM cipher suites T LS_ECDHE_RSA_WIT H_AES_256_GCM_SHA384 or
T LS_ECDHE_RSA_WIT H_AES_128_GCM _SHA256.
1. Using the Microsoft Group Policy Editor, browse to Computer Configuration > Administrative T emplates > Network > SSL
Configuration Settings.
2. Edit the policy “SSL Cipher Suite Order”. By default, this policy is set to “Not Configured”. Set this policy to Enabled.
3. Arrange suites in the correct order; remove any cipher suites suites you do not want to use.
Ensure that either T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA384, or T LS_ECDHE_RSA_WIT H_AES_128_CBC_SHA256
precedes any T LS_DHE_ cipher suites.
On Microsoft MSDN, see also Prioritizing Schannel Cipher Suites.
Change HTTP or HTTPS ports
By default, the XML Service on the Controller listens on port 80 for HT T P traffic and port 443 for HT T PS traffic. Although
you can use non-default ports, be aware of the security risks of exposing a Controller to untrusted networks. Deploying a
standalone StoreFront server is preferable to changing the defaults.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.337
To change the default HT T P or HT T PS ports used by the Controller, run the following command from Studio:
BrokerService.exe -WIPORT < http-port > -WISSLPORT < https-port >
where <http-port > is the port number for HT T P traffic and <https-port > is the port number for HT T PS traffic.
Note
After changing a port, Studio might display a message about license compatibility and upgrading. To resolve the issue, re-register
service instances using the following PowerShell cmdlet sequence:
Get-ConfigRegisteredServiceInstance -ServiceType Broker -Binding XML_HT T PS |
Unregister-ConfigRegisteredServiceInstance
Get-BrokerServiceInstance | where Binding -eq "XML_HT T PS" |
Register-ConfigServiceInstance
Enf orce HTTPS traf fic only
If you want the XML Service to ignore HT T P traffic, create the following registry setting in
HKLM\Software\Citrix\DesktopServer\ on the Controller and then restart the Broker Service.
To ignore HT T P traffic, create DWORD XmlServicesEnableNonSsl and set it to 0.
T here is a corresponding registry DWORD value you can create to ignore HT T PS traffic: DWORD XmlServicesEnableSsl.
Ensure that it is not set to 0.
TLS settings on VDAs
A Delivery Group cannot have a mixture of some VDAs with T LS configured and some VDAs without T LS configured. Before
you configure T LS for a Delivery Group, ensure that you have already configured T LS for all the VDAs in that Delivery Group
When you configure T LS on VDAs, permissions on the installed T LS certificate are changed, giving the ICA Service read
access to the certificate’s private key, and informing the ICA Service of the following:
Which certif icate in the certif icate store to use f or TLS.
Which TCP port number to use f or TLS connections.
T he Windows Firewall (if enabled) must be configured to allow incoming connection on this TCP port. T his configuration is
done for you when you use the PowerShell script.
Which versions of the TLS protocol to allow.
Important
Citrix recommends that you review your use of SSLv3, and reconfigure those deployments to remove support for SSLv3 where
appropriate. See CT X200238.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.338
T he supported T LS protocol versions follow a hierarchy (lowest to highest): SSL 3.0, T LS 1.0, T LS 1.1, and T LS 1.2.
Specify the minimum allowed version; all protocol connections using that version or a higher version are allowed.
For example, if you specify T LS 1.1 as the minimum version, then T LS 1.1 and T LS 1.2 protocol connections are allowed.
If you specify SSL 3.0 as the minimum version, then connections for all the supported versions are allowed. If you
specify T LS 1.2 as the minimum version, only T LS 1.2 connections are allowed.
DT LS 1.0 corresponds to T LS 1.1, and DT LS 1.2 corresponds to T LS 1.2.
Which TLS cipher suites to allow.
A cipher suite selects the encryption that is used for a connection. Clients and VDAs can support different sets of
cipher suites. When a client (Citrix Receiver or StoreFront) connects and sends a list of supported T LS cipher suites,
the VDA matches one of the client’s cipher suites with one of the cipher suites in its own list of configured cipher
suites, and accepts the connection. If there is no matching cipher suite, the VDA rejects the connection.
T he VDA supports three sets of cipher suites (also known as compliance modes): GOV(ernment), COM(mercial), and
ALL. T he acceptable cipher suites also depend on the Windows FIPS mode; see
http://support.microsoft.com/kb/811833 for information about Windows FIPS mode. T he following table lists the
cipher suites in each set:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.339
TLS/DTLS cipher suite
ALL
COM
GOV
ALL
COM
GOV
FIPS Mode
Off
Off
Off
On
On
On
T LS_ECDHE_RSA_WIT H_AES_256_GCM_SHA384**
X
X
X
T LS_ECDHE_RSA_WIT H_AES_128_GCM_SHA256**
X
X
X
T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA384
X
X
X
T LS_ECDHE_RSA_WIT H_AES_128_CBC_SHA256
X
X
X
T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA
X
X
X
T LS_ECDHE_RSA_WIT H_AES_128_CBC_SHA
X
X
X
T LS_RSA_WIT H_AES_256_GCM_SHA384
X
X
X
T LS_RSA_WIT H_AES_128_GCM_SHA256
X
X
X
T LS_RSA_WIT H_AES_256_CBC_SHA256
X
X
X
T LS_RSA_WIT H_AES_128_CBC_SHA256
X
X
X
T LS_RSA_WIT H_AES_256_CBC_SHA
X
X
X
T LS_RSA_WIT H_AES_128_CBC_SHA
X
X
X
T LS_RSA_WIT H_3DES_EDE_CBC_SHA
X
X***
X
T LS_RSA_WIT H_RC4_128_SHA*
X****
X****
T LS_RSA_WIT H_RC4_128_MD5*
X****
X****
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X***
* T hese cipher suites are not supported by DT LS.
** T hese cipher suites are not supported in Windows Server 2012 R2.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.340
*** 3DES is disabled by default in GOV cipher set.
**** RC4-MD5 is disabled by default.
Note
T he VDA does not support DHE ciphersuites (for example, T LS_DHE_RSA_WIT H_AES_256_GCM_SHA384,
T LS_DHE_RSA_WIT H_AES_256_CBC_SHA, T LS_DHE_RSA_WIT H_AES_128_GCM_SHA256, and
T LS_DHE_RSA_WIT H_AES_128_CBC_SHA.) If selected by Windows, they may not be used by Receiver.
Configure TLS on a VDA using the PowerShell script
Install the T LS Certificate in the Local Computer > Personal > Certificates area of the certificate store. If more than one
certificate resides in that location, supply the thumbprint of the certificate to the PowerShell script.
Note
Starting with XenApp and XenDesktop 7.16 LT SR, the PowerShell script finds the correct certificate based on the FQDN of the VDA.
You do not need to supply the thumbprint when only a single certificate is present for the VDA FQDN.
T he Enable-VdaSSL.ps1 script enables or disables the T LS listener on a VDA. T his script is available in the Support >Tools >
SslSupport folder on the installation media.
When you enable T LS, DHE cipher suites are disabled. ECDHE cipher suites are not affected.
When you enable T LS, the script disables all existing Windows Firewall rules for the specified TCP port. It then adds a new
rule that allows the ICA Service to accept incoming connections only on the T LS TCP and UDP ports. It also disables the
Windows Firewall rules for:
Citrix ICA (default: 1494)
Citrix CGP (default: 2598)
Citrix WebSocket (default: 8008)
T he effect is that users can only connect using T LS or DT LS. T hey cannot use ICA/HDX, ICA/HDX with Session Reliability,
or HDX over WebSocket, without T LS or DT LS.
Note
DT LS is not supported with ICA/HDX Audio over UDP Real-time Transport, or with ICA/HDX Framehawk.
See Network ports.
T he script contains the following syntax descriptions, plus extra examples; you can use a tool such as Notepad++ to review
this information.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.341
Important
Specify either the Enable or Disable parameter, and the CertificateT humbPrint parameter. T he other parameters are optional.
Syntax
Enable-VdaSSL {-Enable | -Disable} -CertificateT humbPrint "<thumbprint>"
[– SSLPort <port>] [-SSLMinVersion "<min-ssl-version>"] [-SSLCipherSuite"<suite>"]
Parameter
Description
Enable
Installs and enables the T LS listener on the VDA. Either this parameter or the Disable parameter is required.
Disable
CertificateT humbPrint
"<thumbprint>"
SSLPort <port>
Disables the T LS listener on the VDA. Either this parameter or the Enable parameter is required. If you specify
this parameter, no other parameters are valid.
T humbprint of the T LS certificate in the certificate store, enclosed in quotation marks. T he script uses the
specified thumbprint to select the certificate you want to use. If this parameter is omitted, an incorrect
certificate is selected.
T LS port. Default: 443
Minimum T LS protocol version, enclosed in quotation marks. Valid values:
"SSL_3.0"
"T LS_1.0"
SSLMinVersion
"<version>"
"T LS_1.1"
"T LS_1.2"
Default: "T LS_1.0"
Important: Citrix recommends that customers review their usage of SSLv3 and take steps to reconfigure their
deployments to remove support for SSLv3 where appropriate. See CT X200238.
T LS cipher suite, enclosed in quotation marks. Valid values:
"GOV"
SSLCipherSuite
"COM"
"<suite>"
"ALL"
Default: "ALL"
Examples
T he following script installs and enables the T LS protocol version value. T he thumbprint (represented as
"12345678987654321" in this example) is used to select the certificate to use.
Enable-VdaSSL – Enable -CertificateT humbPrint "12345678987654321"
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.342
T he following script installs and enables the T LS listener, and specifies T LS port 400, the GOV cipher suite, and a minimum
T LS 1.2 protocol value. T he thumbprint (represented as "12345678987654321" in this example) is used to select the
certificate to use.
Enable-VdaSSL – Enable
-CertificateT humbPrint "12345678987654321"
– SSLPort 400 'SSLMinVersion "T LS_1.2"
– SSLCipherSuite "GOV"
T he following script disables the T LS listener on the VDA.
Enable-VdaSSL – Disable
Manually configure TLS on a VDA
When configuring T LS on a VDA manually, you grant generic read access to the private key of the T LS certificate for the
appropriate service on each VDA: NT SERVICE\PorticaService for a VDA for Windows Desktop OS, or NT
SERVICE\TermService for a VDA for Windows Server OS. On the machine where the VDA is installed:
STEP 1. Launch the Microsoft management console (MMC): Start > Run > mmc.exe.
STEP 2. Add the Certificates snap-in to the MMC:
1. Select File > Add/Remove Snap-in.
2. Select Certificates and then click Add.
3. When prompted with "T his snap-in will always manage certificates for:" choose "Computer account" and then click Next.
4. When prompted with "Select the computer you want this snap-in to manage" choose "Local computer" and then click
Finish.
STEP 3. Under Certificates (Local Computer) > Personal > Certificates, right– click the certificate and then select All Tasks >
Manage Private Keys.
STEP 4 . T he Access Control List Editor displays "Permissions for (FriendlyName) private keys" where (FriendlyName) is the
name of your T LS certificate. Add one of the following services and give it Read access:
For a VDA for Windows Desktop OS, "PORT ICASERVICE"
For a VDA for Windows Server OS, "T ERMSERVICE"
STEP 5. Double-click the installed T LS certificate. In the certificate dialog, select the Details tab and then scroll to the
bottom. Click T humbprint.
STEP 6. Run regedit and go to HKLM\SYST EM\CurrentControlSet\Control\Terminal Server\Wds\icawd.
1. Edit the SSL T humbprint key and copy the value of the T LS certificate’s thumbprint into this binary value. You can safely
ignore unknown items in the Edit Binary Value dialog box (such as '0000' and special characters).
2. Edit the SSLEnabled key and change the DWORD value to 1. (T o disable SSL later, change the DWORD value to 0.)
3. If you want to change the default settings (optional), use the following in the same registry path:
SSLPort DWORD – SSL port number. Default: 443.
SSLMinVersion DWORD – 1 = SSL 3.0, 2 = T LS 1.0, 3 = T LS 1.1, 4 = T LS 1.2. Default: 2 (T LS 1.0).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.343
SSLCipherSuite DWORD – 1 = GOV, 2 = COM, 3 = ALL. Default: 3 (ALL).
STEP 7. Ensure that the T LS TCP and UDP ports are that open in the Windows Firewall if they are not the default 443.
(When you create the inbound rule in Windows Firewall, ensure its properties have the "Allow the connection" and "Enabled"
entries selected.)
STEP 8. Ensure that no other applications or services (such as IIS) are using the T LS TCP port.
STEP 9. For VDAs for Windows Server OS, restart the machine for the changes to take effect. (You do not need to restart
machines containing VDAs for Windows Desktop OS.)
Important
An extra step is necessary when the VDA is on Windows Server 2012 R2, Windows Server 2016, or Windows 10 Anniversary Edition
or later supported release. T his affects connections from Citrix Receiver for Windows (version 4.6 through 4.9), Citrix Receiver for
HT ML5, and Citrix Receiver for Chrome. T his also includes connections using NetScaler Gateway.
T his step is also required for all connections using NetScaler Gateway, for all VDA versions, if T LS between the NetScaler Gateway
and the VDA is configured. T his affects all Citrix Receiver versions.
On the VDA (Windows Server 2012 R2, Windows Server 2016, or Windows 10 Anniversary Edition or later), using the Group
Policy Editor, go to Computer Configuration > Administrative Templates > Network > SSL Configuration Settings > SSL
Cipher Suite Order. Select the following order:
T LS_ECDHE_RSA_WIT H_AES_256_GCM_SHA384_P384
T LS_ECDHE_RSA_WIT H_AES_256_GCM_SHA384_P256
T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA384_P384
T LS_ECDHE_RSA_WIT H_AES_256_CBC_SHA384_P256
T LS_RSA_WIT H_AES_256_GCM_SHA384
T LS_RSA_WIT H_AES_128_GCM_SHA256
T LS_RSA_WIT H_AES_256_CBC_SHA256
T LS_RSA_WIT H_AES_256_CBC_SHA
T LS_RSA_WIT H_AES_128_CBC_SHA
T LS_RSA_WIT H_RC4_128_SHA
T LS_RSA_WIT H_3DES_EDE_CBC_SHA
Note
T he first four items also specify the elliptic curve, P384 or P256. Ensure that "curve25519" is not selected. FIPS Mode does not
prevent the use of "curve25519".
When this Group Policy setting is configured, the VDA selects a cipher suite only if appears in both lists: the Group Policy list
and the list for the selected compliance mode (COM, GOV, or ALL). T he cipher suite must also appear in the list sent by the
client (Citrix Receiver or StoreFront).
T his Group Policy configuration also affects other T LS applications and services on the VDA. If your applications require
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.344
specific cipher suites, you may need to add them to this Group Policy list.
Important
Even though Group Policy changes are shown when they are applied, Group Policy changes for T LS configuration only take effect
after an operating system restart. T herefore, for pooled desktops, apply the Group Policy changes for T LS configuration to the base
image.
Configure TLS on Delivery Groups
Complete this procedure for each Delivery Group that contains VDAs you have configured for T LS connections.
1. From Studio, open the PowerShell console.
2. Run asnp Citrix.* to load the Citrix product cmdlets.
3. Run Get-BrokerAccessPolicyRule -DesktopGroupName '< delivery-group-name>' | Set-BrokerAccessPolicyRule HdxSslEnabled $true.
4. Run Set-BrokerSite -DnsResolutionEnabled $true.
Troubleshooting
If a connection error occurs, check the system event log on the VDA.
When using Citrix Receiver for Windows, if you receive a connection error that indicates a T LS error, disable Desktop Viewer
and then try connecting again. Although the connection still fails an explanation of the underlying T LS issue might be
provided. For example, you specified an incorrect template when requesting a certificate from the certificate authority.)
Most configurations that use HDX Adaptive Transport work successfully with DT LS, including those using the latest
versions of Citrix Receiver, NetScaler Gateway, and the VDA. Some configurations which use DT LS between Citrix Receiver
and NetScaler Gateway, and which use DT LS between NetScaler Gateway and the VDA, require additional action.
Additional action is needed if:
the Citrix Receiver version supports HDX Adaptive T ransport and DT LS: Receiver for Windows (4.7, 4.8, 4.9), Receiver for
Mac (12.5, 12.6, 12.7), Receiver for iOS (7.2, 7.3.x) or Receiver for Linux (13.7)
and either of the following also applies:
the NetScaler Gateway version supports DT LS to the VDA, but the VDA version does not support DT LS (version 7.15 or
earlier),
the VDA version supports DT LS (version 7.16 or later), but the NetScaler Gateway version does not support DT LS to the
VDA.
To avoid connections from Citrix Receiver failing, do one of the following:
update Citrix Receiver, to Receiver for Windows version 4.10 or later, Receiver for Mac 12.8 or later, or Receiver for iOS
version 7.5 or later; or,
update the NetScaler Gateway to a version that supports DT LS to the VDA; or,
update the VDA, to version 7.16 or later; or,
disable DT LS at the VDA; or,
disable HDX Adaptive T ransport.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.345
Note
A suitable update for Receiver for Linux is not yet available. Receiver for Android (version 3.12.3) does not support HDX Adaptive
Transport and DT LS via NetScaler Gateway, and is therefore not affected.
To disable DT LS at the VDA, modify the VDA firewall configuration to disable UDP port 443. See Network ports.
Communication between Controller and VDA
Windows Communication Framework (WCF) message-level protection secures communication between the Controller and
the VDA. Extra transport-level protection using T LS is not required. T he WCF configuration uses Kerberos for mutual
authentication between the Controller and VDA. Encryption uses AES in CBC mode with a 256-bit key. Message integrity
uses SHA-1.
According to Microsoft, the Security protocols used by WCF conform to standards from OASIS (Organization for the
Advancement of Structured Information Standards), including WS-SecurityPolicy 1.2. Additionally, Microsoft states that
WCF supports all algorithm suites listed in Security Policy 1.2.
Communication between the Controller and VDA uses the basic256 algorithm suite, whose algorithms are as stated above.
TLS and HTML5 video redirection, and browser content redirection
You can use HT ML5 video redirection and browser content redirection to redirect HT T PS websites. T he JavaScript injected
into those websites must establish a T LS connection to the Citrix HDX HT ML5 Video Redirection Service running on the
VDA. To achieve this, two custom certificates are generated in the certificate store on the VDA.
T he HT ML5 video redirection policy is disabled by default.
T he browser content redirection is enabled by default.
Note
If you do not intend to use HT ML5 video redirection or browser content redirection, we recommend that you delete the two
certificates from the local computer certificate store.
T hese certificates are:
For the CA (root): Citrix XenApp/XenDesktop HDX In-Product CA (C = US; S = Florida; L = Fort Lauderdale; O = Citrix Systems,
Inc.; OU = XenApp/XenDesktop Engineering; CN = Citrix XenApp/XenDesktop HDX In-Product CA)
Location: Certificates (Local Computer) >T rusted Root Certification Authorities >Certificates.
For the end-entity (leaf): Citrix XenApp/XenDesktop HDX Service (C = US; S = Florida; L = Fort Lauderdale; O = Citrix Systems,
Inc.; OU = XenApp/XenDesktop Engineering; CN = Citrix XenApp/XenDesktop HDX Service)
Location: Certificates (Local Computer) > Personal > Certificates.
We recommend setting the Citrix HDX HT ML5 Video Redirection Service so that it doesn't automatically start.
Stopping this service also removes the certificates.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.346
For more information on HT ML5 video redirection, see Multimedia policy settings.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.347
Federated Authentication Service
Nov 28 , 20 17
T he Citrix Federated Authentication Service is a privileged component designed to integrate with Active Directory
Certificate Services. It dynamically issues certificates for users, allowing them to log on to an Active Directory environment
as if they had a smart card. T his allows StoreFront to use a broader range of authentication options, such as SAML
(Security Assertion Markup Language) assertions. SAML is commonly used as an alternative to traditional Windows user
accounts on the Internet.
T he following diagram shows the Federated Authentication Service integrating with a Microsoft Certification Authority
and providing support services to StoreFront and XenApp and XenDesktop Virtual Delivery Agents (VDAs).
Trusted StoreFront servers contact the Federated Authentication Service (FAS) as users request access to the Citrix
environment. T he FAS grants a ticket that allows a single XenApp or XenDesktop session to authenticate with a certificate
for that session. When a VDA needs to authenticate a user, it connects to the FAS and redeems the ticket. Only the FAS
has access to the user certificate’s private key; the VDA must send each signing and decryption operation that it needs to
perform with the certificate to the FAS.
Requirements
T he Federated Authentication Service is supported on Windows servers (Windows Server 2008 R2 or later).
Citrix recommends installing the FAS on a server that does not contain other Citrix components.
T he Windows Server should be secured. It will have access to a registration authority certificate and private key that
allows it to automatically issue certificates for domain users, and it will have access to those user certificates and private
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.348
keys.
In the XenApp or XenDesktop Site:
T he Delivery Controllers must be minimum version 7.9.
T he VDAs must be minimum version 7.9. Check that the Federated Authentication Service Group Policy configuration has
been applied correctly to the VDAs before creating the Machine Catalog in the usual way; see the Configure Group
Policy section for details.
T he StoreFront server must be minimum version 3.6 (this is the version provided with the XenApp and XenDesktop 7.9
ISO).
When planning your deployment of this service, review the Security considerations section.
References:
Active Directory Certificate Services
https://technet.microsoft.com/en-us/library/hh831740.aspx
Configuring Windows for Certificate Logon
http://support.citrix.com/article/CT X206156
Install and setup sequence
1. Install the Federated Authentication Service
2. Enable the Federated Authentication Service plug-in on StoreFront servers
3. Configure Group Policy
4. Use the Federated Authentication Service administration console to: (a) Deploy the provided templates, (b) Set up
certificate authorities, and (c) Authorize the Federated Authentication Service to use your certificate authority
5. Configure user rules
Install the Federated Authentication Service
For security, Citrix recommends that the FAS be installed on a dedicated server that is secured in a similar way to a domain
controller or certificate authority. T he FAS can be installed from the Federated Authentication Service button on the
autorun splash screen when the ISO is inserted.
T his will install the following components:
Federated Authentication Service
PowerShell snap-in cmdlets to remotely configure the Federated Authentication Service
Federated Authentication Service administration console
Federated Authentication Service Group Policy templates (CitrixFederatedAuthenticationService.admx/adml)
Certificate template files for simple certificate authority configuration
Performance counters and event logs
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.349
Enable the Federated Authentication Service plug-in
on a StoreFront store
To enable Federated Authentication Service integration on a StoreFront Store, run the following PowerShell cmdlets as an
Administrator account. If you have more than one store, or if the store has a different name, the path text below may
differ.
command
COPY
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module
$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
To stop using the FAS, use the following PowerShell script:
command
COPY
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module
$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""
Configure the Delivery Controller
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.350
To use the Federated Authentication Service, configure the XenApp or XenDesktop Delivery Controller to trust the
StoreFront servers that can connect to it: run the Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true
PowerShell cmdlet.
Configure Group Policy
After you install the Federated Authentication Service, you must specify the full DNS addresses of the FAS servers in Group
Policy using the Group Policy templates provided in the installation.
Important: Ensure that the StoreFront servers requesting tickets and the VDAs redeeming tickets have identical
configuration of DNS addresses, including the automatic server numbering applied by the Group Policy object.
For simplicity, the following examples configure a single policy at the domain level that applies to all machines; however, that
is not required. T he FAS will function as long as the StoreFront servers, VDAs, and the machine running the FAS
administration console see the same list of DNS addresses. Note that the Group Policy object adds an index number to
each entry, which must also match if multiple objects are used.
Step 1. On the server where you installed the FAS, locate the C:\Program Files\Citrix\Federated Authentication
Service\PolicyDefinitions\CitrixFederatedAuthenticationService.admx file and the en-US folder.
Step 2. Copy these to your domain controller and place them in the C:\Windows\PolicyDefinitions and en-US subfolder.
Step 3. Run the Microsoft Management Console (mmc.exe from the command line). From the menu bar, select File >
Add/Remove Snap-in. Add the Group Policy Management Editor.
When prompted for a Group Policy Object, select Browse and then select Def ault Domain Policy. Alternatively, you can
create and select an appropriate policy object for your environment, using the tools of your choice. T he policy must be
applied to all machines running affected Citrix software (VDAs, StoreFront servers, administration tools).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.351
Step 4 . Navigate to the Federated Authentication Service policy located in Computer Configuration/Policies/Administrative
Templates/Citrix Components/Authentication.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.352
Step 5. Open the Federated Authentication Service policy and select Enabled. T his allows you to select the Show button,
where you configure the DNS addresses of your FAS servers.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.353
Step 6. Enter the DNS addresses of the servers hosting your Federated Authentication Service.
Remember: If you enter multiple addresses, the order of the list must be consistent between StoreFront servers and VDAs.
T his includes blank or unused list entries.
Step 7. Click OK to exit the Group Policy wizard and apply the group policy changes. You may need to restart your
machines (or run gpupdate /f orce from the command line) for the change to take effect.
Enable in-session certificate support
T he Group Policy template includes support for configuring the system for in-session certificates. T his places certificates in
the user’s personal certificate store after logon for application use. For example, if you require T LS authentication to web
servers within the VDA session, the certificate can be used by Internet Explorer. By default, VDAs will not allow access to
certificates after logon.
Using the Federated Authentication Service
administration console
T he Federated Authentication Service administration console is installed as part of the Federated Authentication Service.
An icon (Citrix Federated Authentication Service) is placed in the Start Menu.
T he console attempts to automatically locate the FAS servers in your environment using the Group Policy configuration. If
this fails, see the Configure Group Policy section.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.354
If your user account is not a member of the Administrators group on the machine running the Federated Authentication
Service, you will be prompted for credentials.
T he first time the administration console is used, it guides you through a three-step process that deploys certificate
templates, sets up the certificate authority, and authorizes the Federated Authentication Service to use the certificate
authority. Some of the steps can alternatively be completed manually using OS configuration tools.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.355
Deploy certificate templates
To avoid interoperability issues with other software, the Federated Authentication Service provides three Citrix certificate
templates for its own use.
Citrix_RegistrationAuthority_ManualAuthorization
Citrix_RegistrationAuthority
Citrix_SmartcardLogon
T hese templates must be registered with Active Directory. If the console cannot locate them, the Deploy certificate
templates tool can install them. T his tool must be run as an account that has permissions to administer your Enterprise
forest.
T he configuration of the templates can be found in the XML files with extension .certificatetemplate that are installed
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.356
with the Federated Authentication Service in:
C:\Program Files\Citrix\Federated Authentication Service\CertificateTemplates
If you do not have permission to install these template files, give them to your Active Directory Administrator.
To manually install the templates, you can use the following PowerShell commands:
command
COPY
$template = [System.IO.File]::ReadAllBytes("$Pwd\Citrix_SmartcardLogon.certificatetemplate")
$CertEnrol = New-Object -ComObject X509Enrollment.CX509EnrollmentPolicyWebService
$CertEnrol.InitializeImport($template)
$comtemplate = $CertEnrol.GetTemplates().ItemByIndex(0)
$writabletemplate = New-Object -ComObject X509Enrollment.CX509CertificateTemplateADWritable
$writabletemplate.Initialize($comtemplate)
$writabletemplate.Commit(1, $NULL)
Set up Active Directory Certificate Services
After installing the Citrix certificate templates, they must be published on one or more Microsoft Certification Authority
servers. Refer to the Microsoft documentation on how to deploy Active Directory Certificate Services.
If the templates are not published on at least one server, the Setup certificate authority tool offers to publish them. You
must run this tool as a user that has permissions to administer the certificate authority.
(Certificate templates can also be published using the Microsoft Certification Authority console.)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.357
Authorize the Federated Authentication Service
T he final setup step in the console initiates the authorization of the Federated Authentication Service. T he administration
console uses the Citrix_RegistrationAuthority_ManualAuthorization template to generate a certificate request, and then
sends it to one of the certificate authorities that publish that template.
After the request is sent, it appears in the Pending Requests list of the Microsoft Certification Authority console. T he
certificate authority administrator must choose to Issue or Deny the request before configuration of the Federated
Authentication Service can continue. Note that the authorization request appears as a Pending Request from the FAS
machine account.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.358
Right-click All Tasks and then select Issue or Deny for the certificate request. T he Federated Authentication Service
administration console automatically detects when this process completes. T his can take a couple of minutes.
Configure user rules
A user rule authorizes the issuance of certificates for VDA logon and in-session use, as directed by StoreFront. Each rule
specifies the StoreFront servers that are trusted to request certificates, the set of users for which they can be requested,
and the set of VDA machines permitted to use them.
To complete the setup of the Federated Authentication Service, the administrator must define the default rule by
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.359
switching to the User Rules tab of the FAS administration console, selecting a certificate authority to which the
Citrix_SmartcardLogon template is published, and editing the list of StoreFront servers. T he list of VDAs defaults to Domain
Computers and the list of users defaults to Domain Users; these can be changed if the defaults are inappropriate.
Fields:
Certificate Authority and Certificate Template: T he certificate template and certificate authority that will be used to
issue user certificates. T his should be the Citrix_SmartcardLogon template, or a modified copy of it, on one of the
certificate authorities that the template is published to.
T he FAS supports adding multiple certificate authorities for failover and load balancing, using PowerShell commands.
Similarly, more advanced certificate generation options can be configured using the command line and configuration files.
See the PowerShell and Hardware security modules sections.
In-Session Certificates: T he Available af ter logon check box controls whether a certificate can also be used as an insession certificate. If this check box is not selected, the certificate will be used only for logon or reconnection, and the user
will not have access to the certificate after authenticating.
List of StoreFront servers that can use this rule: T he list of trusted StoreFront server machines that are authorized to
request certificates for logon or reconnection of users. Note that this setting is security critical, and must be managed
carefully.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.360
List of VDA desktops and servers that can be logged into by this rule: T he list of VDA machines that can log users on
using the Federated Authentication Service system.
List of users that StoreFront can log in using this rule: T he list of users who can be issued certificates through the
Federated Authentication Service.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.361
Advanced use
You can create additional rules to reference different certificate templates and authorities, which may be configured to
have different properties and permissions. T hese rules can be configured for use by different StoreFront servers, which will
need to be configured to request the new rule by name. By default, StoreFront requests def ault when contacting the
Federated Authentication Service. T his can be changed using the Group Policy Configuration options.
To create a new certificate template, duplicate the Citrix_SmartcardLogon template in the Microsoft Certification
Authority console, rename it (for example, Citrix_SmartcardLogon2), and modify it as required. Create a new user rule by
clicking Add to reference the new certificate template.
Security considerations
T he Federated Authentication Service has a registration authority certificate that allows it to issue certificates
autonomously on behalf of your domain users. As such, it is important to develop and implement a security policy to
protect the the FAS servers, and to constrain their permissions.
Delegated Enrollment Agents
T he Microsoft Certification Authority allows control of which templates the FAS server can use, as well as limiting which
users the FAS server can issue certificates for.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.362
Citrix strongly recommends configuring these options so that the Federated Authentication Service can only issue
certificates for the intended users. For example, it is good practice to prevent the Federated Authentication Service from
issuing certificates to users in an Administration or Protected Users group.
Access Control List configuration
As described in the Configure user roles section, you must configure a list of StoreFront servers that are trusted to assert
user identities to the Federated Authentication Service when certificates are issued. Similarly, you can restrict which users
will be issued certificates, and which VDA machines they can authenticate to. T his is in addition to any standard Active
Directory or certificate authority security features you configure.
Firewall settings
All communication to FAS servers uses mutually authenticated Windows Communication Foundation (WCF) Kerberos
network connections over port 80.
Event log monitoring
T he Federated Authentication Service and the VDA write information to the Windows Event Log. T his can be used for
monitoring and auditing information. T he Event logs section lists event log entries that may be generated.
Hardware security modules
All private keys, including those of user certificates issued by the Federated Authentication Service, are stored as nonexportable private keys by the Network Service account. T he Federated Authentication Service supports the use of a
cryptographic hardware security module, if your security policy requires it.
Low-level cryptographic configuration is available in the FederatedAuthenticationService.exe.config file. T hese settings
apply when private keys are first created. T herefore, different settings can be used for registration authority private keys
(for example, 4096 bit, T PM protected) and runtime user certificates.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.363
Parameter
Description
ProviderLegacyCsp
When set to true, FAS will use the Microsoft CryptoAPI (CAPI). Otherwise, FAS will use
the Microsoft Cryptography Next Generation API (CNG).
ProviderName
Name of the CAPI or CNG provider to use.
ProviderType
Refers to Microsoft KeyContainerPermissionAccessEntry.ProviderType Property
PROV_RSA_AES 24. Should always be 24 unless you are using an HSM with CAPI and
the HSM vendor specifies otherwise.
KeyProtection
Controls the “Exportable” flag of private keys. Also allows the use of Trusted Platform
Module (T PM) key storage, if supported by the hardware.
KeyLength
Key length for RSA private keys. Supported values are 1024, 2048 and 4096 (default:
2048).
PowerShell SDK
Although the Federated Authentication Service administration console is suitable for simple deployments, the PowerShell
interface offers more advanced options. When you are using options that are not available in the console, Citrix
recommends using only PowerShell for configuration.
T he following command adds the PowerShell cmdlets:
Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Use Get-Help <cmdlet name> to display cmdlet help. T he following table lists several commands where * represents a
standard PowerShell verb (such as New, Get, Set, Remove).
Commands
Overview
*-FasServer
Lists and reconfigures the FAS servers in the current environment.
*-FasAuthorizationCertificate
Manages the Registration Authority certificate.
*-FasCertificateDefinition
Controls the parameters that the FAS uses to generate certificates.
*-FasRule
Manages User Rules configured on the Federated Authentication Service.
*-FasUserCertificate
Lists and manages certificates cached by the Federated Authentication Service.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.364
PowerShell cmdlets can be used remotely by specifying the address of a FAS server.
You can also download a zip file containing all the FAS PowerShell cmdlet help files; see the PowerShell SDK article.
Performance counters
T he Federated Authentication Service includes a set of performance counters for load tracking purposes.
T he following table lists the available counters. Most counters are rolling averages over five minutes.
Name
Description
Active Sessions
Number of connections tracked by the Federated Authentication Service.
Concurrent CSRs
Number of certificate requests processed at the same time.
Private Key ops
Number of private key operations performed per minute.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.365
Request time
Length of time to generate and sign a certificate.
Certificate Count
Number of certificates cached in the Federated Authentication Service.
CSR per minute
Number of CSRs processed per minute.
Low/Medium/High
Estimates of the load that the Federated Authentication Service can accept in terms of
“CSRs per minute”. Exceeding the “High Load” threshold may result in session launches
failing.
Event logs
T he following tables list the event log entries generated by the Federated Authentication Service.
Administration events
[Event Source: Citrix.Authentication.FederatedAuthenticationService]
T hese events are logged in response to a configuration change in the Federated Authentication Service server.
Log Codes
[S001] ACCESS DENIED: User [{0}] is not a member of Administrators group
[S002] ACCESS DENIED: User [{0}] is not an Administrator of Role [{1}]
[S003] Administrator [{0}] setting Maintenance Mode to [{1}]
[S004] Administrator [{0}] enrolling with CA [{1}] templates [{2} and {3}]
[S005] Administrator [{0}] de-authorizing CA [{1}]
[S006] Administrator [{0}] creating new Certificate Definition [{1}]
[S007] Administrator [{0}] updating Certificate Definition [{1}]
[S008] Administrator [{0}] deleting Certificate Definition [{1}]
[S009] Administrator [{0}] creating new Role [{1}]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.366
[S010] Administrator [{0}] updating Role [{1}]
[S011] Administrator [{0}] deleting Role [{1}]
[S012] Administrator [{0}] creating certificate [upn: {0} sid: {1} role: {2}][Certificate Definition: {3}]
[S013] Administrator [{0}] deleting certificates [upn: {0} role: {1} Certificate Definition: {2}]
Log Codes
[S401] Performing configuration upgrade -- [From version {0}][to version {1}]
[S402] ERROR: T he Citrix Federated Authentication Service must be run as Network Service [currently running as: {0}]
Creating identity assertions [Federated Authentication Service]
T hese events are logged at runtime on the Federated Authentication Service server when a trusted server asserts a user
logon.
Log Codes
[S101] Server [{0}] is not authorized to assert identities in role [{1}]
[S102] Server [{0}] failed to assert UPN [{1}] (Exception: {2}{3})
[S103] Server [{0}] requested UPN [{1}] SID {2}, but lookup returned SID {3}
[S104] Server [{0}] failed to assert UPN [{1}] (UPN not allowed by role [{2}])
[S105] Server [{0}] issued identity assertion [upn: {0}, role {1}, Security Context: [{2}]
[S120] Issuing certificate to [upn: {0} role: {1} Security Context: [{2}]]
[S121] Issuing certificate to [upn: {0} role: {1}] on behalf of account {2}
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.367
[S122] Warning: Server is overloaded [upn: {0} role: {1}][Requests per minute {2}].
Acting as a relying party [Federated Authentication Service]
T hese events are logged at runtime on the Federated Authentication Service server when a VDA logs on a user.
Log Codes
[S201] Relying party [{0}] does not have access to a password.
[S202] Relying party [{0}] does not have access to a certificate.
[S203] Relying party [{0}] does not have access to the Logon CSP
[S204] Relying party [{0}] accessing the Logon CSP [Operation: {1}]
[S205] Calling account [{0}] is not a relying party in role [{1}]
[S206] Calling account [{0}] is not a relying party
[S207] Relying party [{0}] asserting identity [upn: {1}] in role: [{2}]
[S208] Private Key operation failed [Operation: {0}][upn: {1} role: {2} certificateDefinition {3}][Error {4} {5}].
In-session certificate server [Federated Authentication Service]
T hese events are logged on the Federated Authentication Service server when a user uses an in-session certificate.
Log Codes
[S301] Access Denied: User [{0}] does not have access to a Virtual Smart Card
[S302] User [{0}] requested unknown Virtual Smart Card [thumbprint: {1}]
[S303] User [{0}] does not match Virtual Smart Card [upn: {1}]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.368
[S304] User [{1}] running program [{2}] on computer [{3}] using Virtual Smart Card [upn: {4} role: {5}] for private key
operation: [{6}]
[S305] Private Key operation failed [Operation: {0}][upn: {1} role: {2} containerName {3}][Error {4} {5}].
Log on [VDA]
[Event Source: Citrix.Authentication.IdentityAssertion]
T hese events are logged on the VDA during the logon stage.
Log Codes
[S101] Identity Assertion Logon failed. Unrecognised Federated Authentication Service [id: {0}]
[S102] Identity Assertion Logon failed. Could not lookup SID for {0} [Exception: {1}{2}]
[S103] Identity Assertion Logon failed. User {0} has SID {1}, expected SID {2}
[S104] Identity Assertion Logon failed. Failed to connect to Federated Authentication Service: {0} [Error: {1} {2}]
[S105] Identity Assertion Logon. Logging in [Username: {0}][Domain: {1}]
[S106] Identity Assertion Logon. Logging in [Certificate: {0}]
[S107] Identity Assertion Logon failed. [Exception: {1}{2}]
[S108] Identity Assertion Subsystem. ACCESS_DENIED [Caller: {0}]
In-session certificates [VDA]
T hese events are logged on the VDA when a user attempts to use an in-session certificate.
Log Codes
[S201] Virtual Smart Card Authorized [User: {0}][PID: {1} Name:{2}][Certificate {3}]
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.369
[S202] Virtual Smart Card Subsystem. No smart cards available in session {0}
[S203] Virtual Smart Card Subsystem. Access Denied [caller: {0}, session {1}, expected: {2}]
[S204] Virtual Smart Card Subsystem. Smart card support disabled.
Certificate request and generation codes [Federated Authentication Service]
[Event Source: Citrix.TrustFabric]
T hese low-level events are logged when the Federated Authentication Service server performs log-level cryptographic
operations.
Log Codes
[S0001]TrustArea::TrustArea: Installed certificate chain
[S0002]TrustArea::Join: Callback has authorized an untrusted certificate
[S0003]TrustArea::Join: Joining to a trusted server
[S0004]TrustArea::Maintain: Renewed certificate
[S0005]TrustArea::Maintain: Retrieved new certificate chain
[S0006]TrustArea::Export: Exporting private key
[S0007]TrustArea::Import: Importing Trust Area
[S0008]TrustArea::Leave: Leaving Trust Area
[S0009]TrustArea::SecurityDescriptor: Setting Security Descriptor
[S0010]CertificateVerification: Installing new trusted certificate
[S0011]CertificateVerification: Uninstalling expired trusted certificate
[S0012]TrustFabricHttpClient: Attempting single sign-on to {0}
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.370
[S0013]TrustFabricHttpClient: Explicit credentials entered for {0}
[S0014]Pkcs10Request::Create: Created PKCS10 request
[S0015]Pkcs10Request::Renew: Created PKCS10 request
[S0016]PrivateKey::Create
[S0017]PrivateKey::Delete
[S0018]TrustArea::TrustArea: Waiting for Approval
[S0019]TrustArea::Join: Delayed Join
[S0020]TrustArea::Join: Delayed Join
[S0021]TrustArea::Maintain: Installed certificate chain
Log Codes
[S0101]TrustAreaServer::Create root certificate
[S0102]TrustAreaServer::Subordinate: Join succeeded
[S0103]TrustAreaServer::PeerJoin: Join succeeded
[S0104]MicrosoftCertificateAuthority::GetCredentials: Authorized to use {0}
[S0104]MicrosoftCertificateAuthority::SubmitCertificateRequest Error {0}
[S0105]MicrosoftCertificateAuthority::SubmitCertificateRequest Issued cert {0}
[S0106]MicrosoftCertificateAuthority::PublishCRL: Published CRL
[S0107]MicrosoftCertificateAuthority::ReissueCertificate Error {0}
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.371
[S0108]MicrosoftCertificateAuthority::ReissueCertificate Issued Cert {0}
[S0109]MicrosoftCertificateAuthority::CompleteCertificateRequest - Still waiting for approval
[S0110]MicrosoftCertificateAuthority::CompleteCertificateRequest - Pending certificate refused
[S0111]MicrosoftCertificateAuthority::CompleteCertificateRequest Issued certificate
[S0112]MicrosoftCertificateAuthority::SubmitCertificateRequest - Waiting for approval
[S0120]NativeCertificateAuthority::SubmitCertificateRequest Issued cert {0}
[S0121]NativeCertificateAuthority::SubmitCertificateRequest Error
[S0122]NativeCertificateAuthority::RootCARollover New root certificate
[S0123]NativeCertificateAuthority::ReissueCertificate New certificate
[S0124]NativeCertificateAuthority::RevokeCertificate
[S0125]NativeCertificateAuthority::PublishCRL
Related information
T he common FAS deployments are summarized in the Federated Authentication Service architectures overview article.
"How-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.372
Federated Authentication Service architectures
overview
Nov 28 , 20 17
Introduction
T he Federated Authentication Service (FAS) is a Citrix component that integrates with your Active Directory certificate
authority (CA), allowing users to be seamlessly authenticated within a Citrix environment. T his document describes various
authentication architectures that may be appropriate for your deployment.
When enabled, the FAS delegates user authentication decisions to trusted StoreFront servers. StoreFront has a
comprehensive set of built-in authentication options built around modern web technologies, and is easily extensible using
the StoreFront SDK or third-party IIS plugins. T he basic design goal is that any authentication technology that can
authenticate a user to a web site can now be used to log in to a Citrix XenApp or XenDesktop deployment.
T his document covers some example top-level deployment architectures, in increasing complexity.
Internal deployment
NetScaler Gateway deployment
ADFS SAML
B2B account mapping
Windows 10 Azure AD join
Links are provided to related FAS articles. For all architectures, the Federated Authentication Service article is the primary
reference for setting up the FAS.
How it works
T he FAS is authorized to issue smart card class certificates automatically on behalf of Active Directory users who are
authenticated by StoreFront. T his uses similar APIs to tools that allow administrators to provision physical smart cards.
When a user is brokered to a Citrix XenApp or XenDesktop Virtual Delivery Agent (VDA), the certificate is attached to the
machine, and the Windows domain sees the logon as a standard smart card authentication.
Internal deployment
T he FAS allows users to securely authenticate to StoreFront using a variety of authentication options (including Kerberos
single sign-on) and connect through to a fully authenticated Citrix HDX session.
T his allows Windows authentication without prompts to enter user credentials or smart card PINs, and without using
“saved password management” features such as the Single Sign-on Service. T his can be used to replace the Kerberos
Constrained Delegation logon features available in earlier versions of XenApp.
All users have access to public key infrastructure (PKI) certificates within their session, regardless of whether or not they log
on to the endpoint devices with a smart card. T his allows a smooth migration to two-factor authentication models, even
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.373
from devices such as smartphones and tablets that do not have a smart card reader.
T his deployment adds a new server running the FAS, which is authorized to issue smart card class certificates on behalf of
users. T hese certificates are then used to log on to user sessions in a Citrix HDX environment as if a smart card logon was
used.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.374
T he XenApp or XenDesktop environment must be configured in a similar manner as smart card logon, which is documented
in CT X206156.
In an existing deployment, this usually involves only ensuring that a domain-joined Microsoft certificate authority (CA) is
available, and that domain controllers have been assigned domain controller certificates. (See the "Issuing Domain
Controller Certificates" section in CT X206156.)
Related information:
Keys can be stored in a Hardware Security Module (HSM) or built-in T rusted Platform Module (T PM). For details, see the
Federated Authentication Service private key protection article.
T he Federated Authentication Service article describes how to install and configure the FAS.
NetScaler Gateway deployment
T he NetScaler deployment is similar to the internal deployment, but adds Citrix NetScaler Gateway paired with StoreFront,
moving the primary point of authentication to NetScaler itself. Citrix NetScaler includes sophisticated authentication and
authorization options that can be used to secure remote access to a company's web sites.
T his deployment can be used to avoid multiple PIN prompts that occur when authenticating first to NetScaler and then
logging in to a user session. It also allows use of advanced NetScaler authentication technologies without additionally
requiring AD passwords or smart cards.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.375
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.376
T he XenApp or XenDesktop environment must be configured in a similar manner as smart card logon, which is documented
in CT X206156.
In an existing deployment, this usually involves only ensuring that a domain-joined Microsoft certificate authority (CA) is
available, and that domain controllers have been assigned Domain Controller certificates. (See the “Issuing Domain
Controller Certificates” section in CT X206156).
When configuring NetScaler as the primary authentication system, ensure that all connections between NetScaler and
StoreFront are secured with T LS. In particular, ensure that the Callback Url is correctly configured to point to the NetScaler
server, as this can be used to authenticate the NetScaler server in this deployment.
Related information:
T o configure NetScaler Gateway, see “How to Configure NetScaler Gateway 10.5 to use with StoreFront 3.6 and
XenDesktop 7.6."
T he Federated Authentication Service article describes how to install and configure the FAS.
ADFS SAML deployment
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.377
A key NetScaler authentication technology allows integration with Microsoft ADFS, which can act as a SAML Identity
Provider (IdP). A SAML assertion is a cryptographically-signed XML block issued by a trusted IdP that authorizes a user to
log on to a computer system. T his means that the FAS server now allows the authentication of a user to be delegated to
the Microsoft ADFS server (or other SAML-aware IdP).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.378
ADFS is commonly used to securely authenticate users to corporate resources remotely over the Internet; for example, it is
often used for Office 365 integration.
Related information:
T he Federated Authentication Service ADFS deployment article contains details.
T he Federated Authentication Service article describes how to install and configure FAS.
T he NetScaler Gateway deployment section in this article cntains configuration considerations.
B2B account mapping
If two companies want to use each other’s computer systems, a common option is to set up an Active Directory
Federation Service (ADFS) server with a trust relation. T his allows users in one company to seamlessly authenticate into
another company’s Active Directory (AD) environment. When logging on, each user uses their own company logon
credentials; ADFS automatically maps this to a “shadow account” in the peer company’s AD environment.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.379
Related information:
T he Federated Authentication Service article describes how to install and configure FAS.
Windows 10 Azure AD Join
Windows 10 introduced the concept of “Azure AD Join,” which is conceptually similar to traditional Windows domain join but
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.380
targeted at “over the internet” scenarios. T his works well with laptops and tablets. As with traditional Windows domain
join, Azure AD has functionality to allow single sign-on models for company websites and resources. T hese are all “Internet
aware,” so will work from any Internet connected location, not just the office LAN.
T his deployment is an example where there is effectively no concept of “end users in the office.” Laptops are enrolled and
authenticate entirely over the Internet using modern Azure AD features.
Note that the infrastructure in this deployment can run anywhere an IP address is available: on-premises, hosted provider,
Azure, or another cloud provider. T he Azure AD Connect synchronizer will automatically connect to Azure AD. T he example
graphic uses Azure VMs for simplicity.
Related information:
T he Federated Authentication Service article describes how to install and configure FAS.
T he Federated Authentication Service Azure AD integration article contains details.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.381
Federated Authentication Service ADFS deployment
Nov 28 , 20 17
Introduction
T his document describes how to integrate a Citrix environment with Microsoft ADFS.
Many organizations use ADFS to manage secure user access to web sites that require a single point of authentication. For
example, a company may have additional content and downloads that are available to employees; those locations need to
be protected with standard Windows logon credentials.
T he Federated Authentication Service (FAS) also allows Citrix NetScaler and Citrix StoreFront to be integrated with the
ADFS logon system, reducing potential confusion for the company’s staff.
T his deployment integrates NetScaler as a relying party to Microsoft ADFS.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.382
SAML overview
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.383
Security Assertion Markup Language (SAML) is a simple “redirect to a logon page” web browser logon system.
Configuration includes the following items:
Redirect URL [Single Sign-on Service Url]
When NetScaler discovers that a user needs to be authenticated, it instructs the user’s web browser to do a HT T P POST
to a SAML logon webpage on the ADFS server. T his is usually an https:// address of the form:
https://adfs.mycompany.com/adfs/ls.
T his web page POST includes other information, including the “return address” where ADFS will return the user when logon
is complete.
Identifier [Issuer Name/EntityID]
T he EntityId is a unique identifier that NetScaler includes in its POST data to ADFS. T his informs ADFS which service the
user is trying to log on to, and to apply different authentication policies as appropriate. If issued, the SAML authentication
XML will only be suitable for logging on to the service identified by the EntityId.
Usually, the EntityID is the URL of the NetScaler server logon page, but it can generally be anything, as long as NetScaler
and ADFS agree on it: https://ns.mycompany.com/application/logonpage.
Return address [Reply URL]
If authentication is successful, ADFS instructs the user’s web browser to POST a SAML authentication XML back to one of
the Reply URLs that are configured for the EntityId. T his is usually an https:// address on the original NetScaler server in the
form: https://ns.mycompany.com/cgi/samlauth
If there is more than one Reply URL address configured, NetScaler can choose one in its original POST to ADFS.
Signing certificate [IDP Certificate]
ADFS cryptographically signs SAML authentication XML blobs using its private key. To validate this signature, NetScaler
must be configured to check these signatures using the public key included in a certificate file. T he certificate file will usually
be a text file obtained from the ADFS server.
Single sign-out Url [Single Logout URL]
ADFS and NetScaler support a “central logout” system. T his is a URL that NetScaler polls occasionally to check that the
SAML authentication XML blob still represents a currently logged-on session.
T his is an optional feature that does not need to be configured. It is usually an https:// address in the form
https://adfs.mycompany.com/adfs/logout. (Note that it can be the same as the Single Logon URL.)
Configuration
T he NetScaler Gateway deployment section in the Federated Authentication Services architectures article describes how
to set up NetScaler Gateway to handle standard LDAP authentication options, using the XenApp and XenDesktop
NetScaler setup wizard. After that completes successfully, you can create a new authentication policy on NetScaler that
allows SAML authentication. T his can then replace the default LDAP policy used by the NetScaler setup wizard.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.384
Fill in the SAML policy
Configure the new SAML IdP server using information taken from the ADFS management console earlier. When this policy is
applied, NetScaler redirects the user to ADFS for logon, and accepts an ADFS-signed SAML authentication token in return.
Related information
T he Federated Authentication Service article is the primary reference for FAS installation and configuration.
T he common FAS deployments are summarized in the Federated Authentication Service architectures overview article.
"How-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.385
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.386
Federated Authentication Service Azure AD integration
Nov 28 , 20 17
In this article:
Introduction
Architecture
Create a DNS zone
Create a Cloud Service
Create Windows virtual machines
Configure an internal DNS
Configure an external DNS address
Configure security groups
Create an ADFS certificate
Set up Azure AD
Enable Azure AD Join
Install XenApp or XenDesktop
Configure a new Azure AD application for Single Sign-on to StoreFront
Install and configure NetScaler Gateway
Configure the StoreFront address
Enable NetScaler SAML authentication support
Verify the end-to-end system
Appendix
Introduction
T his document describes how to integrate a Citrix environment with the Windows 10 Azure AD feature.
Windows 10 introduced Azure AD, which is a new domain join model where roaming laptops can be joined to a corporate
domain over the Internet for the purposes of management and single sign-on.
T he example deployment in this document describes a system where IT provides new users with a corporate email address
and enrollment code for their personal Windows 10 laptops. Users access this code through the System > About > Join
Azure AD option in the Settings panel.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.387
After the laptop is enrolled, the Microsoft Edge web browser automatically signs on to company web sites and Citrix
published applications through the Azure SaaS applications web page, with other Azure applications such as Office 365.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.388
Architecture
T his architecture replicates a traditional company network completely within Azure, integrating with modern cloud
technologies such as Azure AD and Office 365. End users are all considered remote workers, with no concept of being on
an office intranet.
T he model can be applied to companies with existing on premises systems, because the Azure AD Connect Synchronization
can bridge to Azure over the Internet.
Secure connections and single sign-on, which would traditionally have been firewalled-LAN and Kerberos/NT LM
authentication, are replaced in this architecture by T LS connections to Azure and SAML. New services are built as Azure
applications joined to Azure AD. Existing applications that require Active Directory (such as a SQL Server database) can be
run using a standard Active Directory Server VM in the IAAS portion of the Azure Cloud Service.
When a user launches a traditional application, they are accessed using XenApp and XenDesktop published applications.
T he different types of applications are collated through the user’s Azure Applications page, using the Microsoft Edge
Single sign-on features. Microsoft also supplies Android and iOS apps that can enumerate and launch Azure applications.
Create a DNS zone
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.389
Azure AD requires that the administrator has registered a public DNS address and controls the delegation zone for the
domain name suffix. To do this, the administrator can use the Azure DNS zone feature.
T his example uses the DNS zone name “citrixsamldemo.net.”
T he console shows the names of the Azure DNS name servers. T hese should be referenced in the DNS registrar’s NS
entries for the zone (for example, citrixsamldemo.net. NS n1-01.azure-dns.com)
When adding references to VMs running in Azure, it is easiest to use a CNAME pointer to the Azure-managed DNS record
for the VM. If the IP address of the VM changes, you will not need to manually update the DNS zone file.
Both internal and external DNS address suffixes will match for this deployment. T he domain is citrixsamldemo.net, and uses
a split DNS (10.0.0.* internally).
Add an “fs.citrixsamldemo.net” entry that references the Web Application Proxy server. T his is the Federation Service for
this zone.
Create a Cloud Service
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.390
T his example configures a Citrix environment, including an AD environment with an ADFS server running in Azure. A Cloud
Service is created, named "citrixsamldemo."
Create Windows virtual machines
Create five Windows VMs running in the Cloud Service:
Domain controller (domaincontrol)
Azure Connect ADFS server (adfs)
ADFS web access proxy (Web Application Proxy, not domain joined)
Citrix XenDesktop Delivery Controller (ddc)
Citrix XenDesktop Virtual Delivery Agent (vda)
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.391
Domain Controller
Add the DNS Server and Active Directory Domain Services roles to create a standard Active Directory deployment (in
this example, citrixsamldemo. net). After domain promotion completes, add the Active Directory Certif ication Services
role.
Create a normal user account for testing (for example, George@citrixsamldemo.net).
Since this server will be running internal DNS, all servers should refer to this server for DNS resolution. T his can be done
through the Azure DNS settings page. (For more information, see the Appendix in this document.)
ADFS controller and Web Application Proxy server
Join the ADFS server to the citrixsamldemo domain. T he Web Application Proxy server should remain in an isolated
workgroup, so manually register a DNS address with the AD DNS.
Run the Enable-PSRemoting –Force cmdlet on these servers, to allow PS remoting through firewalls from the AzureAD
Connect tool.
XenDesktop Delivery Controller and VDA
Install the XenApp or XenDesktop Delivery Controller and VDA on the remaining two Windows servers joined to
citrixsamldemo.
Configure an internal DNS
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.392
After the domain controller is installed, configure the DNS server to handle the internal view of citrixsamldemo.net, and act
as a forwarder to an external DNS server (for example: 8.8.8.8).
Add a static record for:
wap.citrixsamldemo.net [the Web Application Proxy VM will not be domain joined]
fs.citrixsamldemo.net [internal federation server address]
enterpriseregistration.citrixsaml.net [same as fs.citrixsamldemo.net]
All VMs running in Azure should be configured to use only this DNS server. You can do this through the Network Interface
GUI.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.393
By default, the internal IP (10.0.0.9) address is dynamically allocated. You can use the IP addresses setting to permanently
assign the IP address. T his should be done for the Web Application Proxy server and the domain controller.
Configure an external DNS address
When a VM is running, Azure maintains its own DNS zone server that points to the current public IP address assigned to the
VM. T his is a useful feature to enable because Azure assigns IP addresses when each VM starts, by default.
T his example assigns a DNS address of domaincontrol-citrixsamldemo.westeurope.cloudapp.azure.com to the domain
controller.
Note that when remote configuration is complete, only the Web Application Proxy and NetScaler VMs should have public
IP addresses enabled. (During configuration, the public IP address is used for RDP access to the environment).
Configure security groups
T he Azure cloud manages firewall rules for TCP/UDP access into VMs from the Internet using security groups. By default,
all VMs allow RDP access. T he NetScaler and Web Application Proxy servers should also allow T LS on port 443.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.394
Create an ADFS certificate
Enable the Web Server certificate template on the Microsoft certificate authority (CA). T his allows creation of a
certificate with custom DNS addresses that can be exported (including private key) to a pfx file. You must install this
certificate on both the ADFS and Web Application Proxy servers, so the PFX file is the preferred option.
Issue a Web Server certificate with the following subject names:
Commonname:
adfs.citrixsamldemo.net [name of computer]
SubjectAltname:
*.citrixsamldemo.net [name of zone]
fs.citrixsamldemo. net [entry in DNS]
enterpriseregistration.citrixsamldemo.net
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.395
Export the certificate to a pfx file, including a password-protected private key.
Set up Azure AD
T his section details the process of setting up a new Azure AD instance and creating user identities that can be used to join
Windows 10 to Azure AD.
Create a new directory
Log on to the classic Azure portal and create a new directory.
When complete, a summary page appears.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.396
Create a global administrator user (AzureAdmin)
Create a global administrator in Azure (in this example, AzureAdmin@citrixsamldemo.onmicrosoft.com) and log on with the
new account to set up a password.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.397
Register your domain with Azure AD
By default, users are identified with an email address in the form: <user.name>@<company>.onmicrosoft.com.
Although this works without further configuration, a standard format email address is better, preferably one that matches
the email account of the end user: <user.name>@<company>.com
T he Add domain action configures a redirect from your real company domain. T he example uses citrixsamldemo.net.
If you are setting up ADFS for single sign-on, enable the check box.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.398
Install Azure AD Connect
Step 2 of the Azure AD configuration GUI redirects to the Microsoft download page for Azure AD Connect. Install this on
the ADFS VM. Use Custom install, rather than Express Settings, so that ADFS options are available.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.399
Select the Federation with AD FS Single sign-On option.
Connect to Azure with the administrator account you created earlier.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.400
Select the internal AD forest.
Synchronize all legacy Active Directory objects with Azure AD.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.401
If the directory structure is simple, you can rely on the usernames being sufficiently unique to identify a user who logs on.
Accept the default filtering options, or restrict users and devices to a particular set of groups.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.402
If desired, you can synchronize the Azure AD passwords with Active Directory. T his is usually not required for ADFS-based
authentication.
Select the certificate PFX file to use in AD FS, specifying fs.citrixsamldemo.net as the DNS name.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.403
When prompted to select a proxy server, enter the address of the wap.citrixsamldemo.net server. You may need to run the
Enable-PSRemoting –Force cmdlet as an administrator on the Web Application Proxy server, so that Azure AD Connect can
configure it.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.404
Note: If this step fails due to Remote PowerShell trust problems, try joining the Web Application Proxy server to the
domain.
For the remaining steps of the wizard, use the standard administrator passwords, and create a service account for ADFS.
Azure AD Connect will then prompt to validate the ownership of the DNS zone.
Add the T XT and MX records to the DNS address records in Azure.
Click Verif y in the Azure Management Console.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.405
Note: If this step fails, you can verify the domain before running Azure AD Connect.
When complete, the external address fs.citrixsamldemo.net is contacted over port 443.
Enable Azure AD Join
When a user enters an email address so that Windows 10 can perform Azure AD join, the DNS suffix is used to construct a
CNAME DNS record that should point to ADFS: enterpriseregistration.<upnsuffix>.
In the example, this is fs.citrixsamldemo.net.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.406
If you are not using a public CA, ensure that the ADFS root certificate is installed on the Windows 10 computer so that
Windows trusts the ADFS server. Perform an Azure AD domain join using the standard user account generated earlier.
Note that the UPN must match the UPN recognized by the ADFS domain controller.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.407
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.408
Verify that the Azure AD join was successful by restarting the machine and logging on, using the user’s email address. When
logged on, launch Microsoft Edge and connect to http://myapps.microsoft.com. T he web site should use single sign-on
automatically.
Install XenApp or XenDesktop
You can install the Delivery Controller and VDA virtual machines in Azure directly from the XenApp or XenDesktop ISO in the
usual way.
In this example, StoreFront is installed on the same server as the Delivery Controller. T he VDA is installed as a standalone
Windows 2012 R2 RDS worker, without integrating with Machine Creation Services (although that can optionally be
configured). Check that the user George@citrixsamldemo.net can authenticate with a password, before continuing.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.409
Run the Set-BrokerSite –TrustRequestsSentToTheXmlServicePort $true PowerShell cmdlet on the Controller to allow
StoreFront to authenticate without the users’ credentials.
Install the Federated Authentication Service
Install the Federated Authentication Service (FAS) component on the ADFS server and configure a rule for the Controller to
act as a trusted StoreFront.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.410
Configure StoreFront
Request a computer certificate for the Delivery Controller, and configure IIS and StoreFront to use HT T PS by setting an IIS
binding for port 443, and changing the StoreFront base address to https:.
Configure StoreFront to use the FAS server (use the PowerShell script in the Federated Authentication Service article), and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.411
test internally within Azure, ensuring that the logon uses the FAS by checking the event viewer on the FAS server.
Configure StoreFront to use NetScaler
Using the Manage Authentication Methods GUI in the StoreFront management console, configure StoreFront to use
NetScaler to perform authentication.
To integrate NetScaler authentication options, configure a Secure T icket Authority (STA) and configure the NetScaler
Gateway address.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.412
Configure a new Azure AD application for Single Signon to StoreFront
T his section uses the Azure AD SAML 2.0 Single Sign-on features, which currently require an Azure Active Directory Premium
subscription. In the Azure AD management tool, select New Application, choosing Add an application f rom the Gallery.
Select CUSTOM > Add an unlisted application my organization is using to create a new custom application for your
users.
Configure an icon
Create an image 215 by 215 pixels in size and upload it on the CONFIGURE page to use as an icon for the application.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.413
Configure SAML authentication
Return to the Application dashboard overview page and select Configure Single sign-on.
T his deployment will use SAML 2.0 authentication, which corresponds to Microsof t Azure AD Single Sign-On.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.414
T he Identifier can be an arbitrary string (it must match the configuration provided to NetScaler); in this example, the Reply
URL is /cgi/samlauth on the NetScaler server.
T he next page contains information that is used to configure NetScaler as a relying party to Azure AD.
Download the base 64 trusted signing certificate and copy the sign-on and sign-out URLs. You will paste these in NetScaler
configuration screens later.
Assign the application to users
T he final step is to enable the application so that it appears on users’ “myapps.microsoft.com” control page. T his is done on
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.415
the USERS AND GROUPS page. Assign access for the domain users accounts synchronized by Azure AD Connect. Other
accounts can also be used, but they must be explicitly mapped because they do not conform to the <user>@<domain>
pattern.
MyApps page
When the application has been configured, it appears on the users’ lists of Azure applications when they visit
https://myapps.microsoft.com.
When it is Azure AD joined, Windows 10 supports single sign-on to Azure applications for the user who logs on. Clicking the
icon takes the browser to the SAML cgi/samlauth web page that was configured earlier.
Single sign-on URL
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.416
Return to the application in the Azure AD dashboard. T here is now a single sign-on URL available for the application. T his
URL is used to provide web browser links or to create Start menu shortcuts that take users directly into StoreFront.
Paste this URL into a web browser to ensure that you are redirected by Azure AD to the NetScaler cgi/samlauth web page
configured earlier. T his works only for users who have been assigned, and will provide single sign-on only for Windows 10
Azure AD-joined logon sessions. (Other users will be prompted for Azure AD credentials.)
Install and configure NetScaler Gateway
To remotely access the deployment, this example uses a separate VM running NetScaler. T his can be purchased from the
Azure Store. T his example uses the “Bring your own License” version of NetScaler 11.0.
Log on to the NetScaler VM, pointing a web browser to the internal IP address, using the credentials specified when the
user authenticated. Note that you must change the password of the nsroot user in an Azure AD VM.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.417
Add licenses, selecting reboot after each license file is added, and point the DNS resolver to the Microsoft domain
controller.
Run the XenApp and XenDesktop setup wizard
T his example starts by configuring a simple StoreFront integration without SAML. After that deployment is working, it adds
a SAML logon policy.
Select the standard NetScaler StoreFront settings. For use in Microsoft Azure, this example configures port 4433, rather
than port 443. Alternatively, you can port-forward or remap the NetScaler administrative web site.
For simplicity, the example uploads an existing server certificate and private key stored in a file.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.418
Configure the domain controller f or AD account management
T he domain controller will be used for account resolution, so add its IP address into the primary authentication method.
Note the formats expected in each field in the dialog box.
Configure the StoreFront address
In this example, StoreFront has been configured using HT T PS, so select the SSL protocol options.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.419
Verif y the NetScaler deployment
Connect to NetScaler and check that authentication and launch are successful with the username and password.
Enable NetScaler SAML authentication support
Using SAML with StoreFront is similar to using SAMl with other web sites. Add a new SAML policy, with an expression of
NS_TRUE.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.420
Configure the new SAML IdP server, using information obtained from Azure AD earlier.
Verify the end-to-end system
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.421
Log on to an Azure AD Joined Windows 10 desktop, using an account registered in Azure AD. Launch Microsoft Edge and
connect to: https://myapps.microsoft.com.
T he web browser should display the Azure AD applications for the user.
Verify that clicking the icon redirects you to an authenticated StoreFront server.
Similarly, verify that direct connections using the Single Sign-on URL and a direct connection to the NetScaler site redirect
you to Microsoft Azure and back.
Finally, verify that non-Azure AD joined machines also function with the same URLs (although there will be a single explicit
sign-on to Azure AD for the first connection).
Appendix
Several standard options should be configured when setting up a VM in Azure.
Provide a public IP address and DNS address
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.422
Azure gives all VMs an IP address on the internal subnet (10.*.*.* in this example). By default a public IP address is also
supplied, which can be referenced by a dynamically updated DNS label.
Select Configuration of the Public IP address/DNS name label. Choose a public DNS address for the VM. T his can be
used for CNAME references in other DNS zone files, ensuring that all DNS records remain correctly pointing to the VM, even
if the IP address is reallocated.
Set up firewall rules (security group)
Each VM in a cloud has a set of firewall rules applied automatically, known as the security group. T he security group
controls traffic forwarded from the public to the private IP address. By default, Azure allows RDP to be forwarded to all
VMs. T he NetScaler and ADFS servers must also need to forward T LS traffic (443).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.423
Open Network Interf aces for a VM, and then click the Network Security Group label. Configure the Inbound security
rules to allow appropriate network traffic.
Related information
T he Federated Authentication Service article is the primary reference for FAS installation and configuration.
T he common FAS deployments are summarized in the Federated Authentication Service architectures overview article.
"How-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.424
Federated Authentication System how-to:
configuration and management
Nov 28 , 20 17
T he following "how-to" articles provide advanced configuration and management guidance for the Federated
Authentication System (FAS):
Private key protection
Certificate authority configuration
Security and network management
T roubleshoot Windows logon issues
PowerShell SDK cmdlet help files
Related information:
T he primary reference for FAS installation and initial setup is the Federated Authentication Service article.
T he Federated Authentication Service architectures overview article provides summaries of the major FAS architectures,
plus links to other articles about the more complex architectures.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.425
Federated Authentication Service certificate authority
configuration
Nov 28 , 20 17
T his article describes the advanced configuration of the Citrix Federated Authentication Service (FAS) to integrate with
certificate authority (CA) servers that are not supported by the FAS administration console. T he instructions use PowerShell
APIs provided by FAS. You should have a basic knowledge of PowerShell before executing any instructions in this article.
Set up multiple CA servers for use in FAS
T his section describes how to set up a single FAS server to use multiple CA servers to issue certificates. T his allows load
balancing and failover of the CA servers.
Step 1: Find out how many CA servers FAS is able to locate
Use the Get-FASMsCertificateAuthority cmdlet to determine which CA servers FAS can connect to. T he following example
shows that FAS can connect to three CA servers.
Step 2: Modif y the existing certificate definition
Citrix recommends that you create a role using the FAS administration console, rather than using PowerShell to create the
role. T his avoids the complication of having to add the SDL manually later. In the following example, a role named ‘default’ is
created, with the access rule configured:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.426
To add multiple CAs to the certificate authority field (which is not supported from the administration console in this release),
you must configure the certificate definition. First, you need the certificate definition name. T he name cannot be
determined from the administration console; use the Get-FASCertificateDefinition cmdlet.
T he UI equivalent is:
After you have the certificate definition name, modify the certificate definition to have a list of CertificateAuthorities,
rather than just one:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.427
T he Get-FASCertificateDefinition cmdlet now returns:
Note: Your FAS administration console will not be functional after doing this. You will see an empty field in both ‘Certificate
Authority” and “Certificate Template” upon loading:
Functionally, FAS is still fine. If you use the console to modify the access rule, just repeat step 2 to display all the certificate
authorities.
Expected behavior changes
After you configure the FAS server with multiple CA servers, user certificate generation is distributed among all the
configured CA servers. Also, if one of the configured CA servers fails, the FAS server will switch to another available CA server.
Configure the Microsoft CA for TCP access
By default the Microsoft CA uses DCOM for access. T his can result in complexities when implementing firewall security, so
Microsoft has a provision to switch to a static TCP port. On the Microsoft CA, open the DCOM configuration panel and
edit the properties of the “CertSrv Request” DCOM application:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.428
Change the “Endpoints” to select a static endpoint and specify a TCP port number (900 in the graphic above).
Restart the Microsoft CA and submit a certificate request. If you run “netstat – a – n – b” you should see that certsvr is now
listening on port 900:
T here is no need to configure the FAS server (or any other machines using the CA), because DCOM has a negotiation stage
using the RPC port. When a client needs to use DCOM, it connects to the DCOM RPC Service on the certificate server and
requests access to a particular DCOM server. T his triggers port 900 to be opened, and the DCOM server instructs the FAS
server how to connect.
Pre-generate user certificates
T he logon time for users will significantly improve when user certificates are pre-generated within the FAS server. T he
following sections describe how it can be done, either for single or multiple FAS servers.
Get a list of Active Directory users
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.429
You can improve certificate generation by querying the AD and storing the list of users into a file (for example, a .csv file), as
shown in the following example.
Get-ADUser is a standard cmdlet to query for a list of users. T he example above contains a filter argument to list only users
with a UserPrincipalName and an account status of ‘enabled.'
T he SearchBase argument narrows which part of the AD to search for users. You can omit this if you want to include all
users in AD. Note: T his query might return a large number of users.
T he CSV looks something like this:
FAS server
T he following PowerShell script takes the previously-generated user list and creates a list of user certificates.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.430
If you have more than one FAS server, a particular user’s certificate will be generated twice: one in the main server, and the
other in the failover server.
T he script above is catered for a rule named ‘default’. If you have a different rule name (for example, ‘hello’), just change the
$rule variable in the script.
Renew registration authority certificates
If more than one FAS server is in use, you can renew a FAS authorization certificate without affecting logged-on users.
Note: Although you can also use the GUI to deauthorize and reauthorize FAS, that has the effect of resetting FAS
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.431
configuration options.
Complete the following sequence:
1. Create a new authorization certificate:
New-FasAuthorizationCertificate
2. Note the GUID of the new authorization certificate, as returned by:
Get-FasAuthorizationCertificate
3. Place the FAS server into maintenance mode:
Set-FasServer – Address <FAS server> -MaintenanceMode $true
4. Swap the new authorization certificate:
Set-FasCertificateDefinition – AuthorizationCertificate <GUID>
5. Take the FAS server out of maintenance mode:
Set-FasServer – Address <FAS server> -MaintenanceMode $false
6. Delete the old authorization certificate:
Remove-FasAuthorizationCertificate
Related information
T he Federated Authentication Service article is the primary reference for FAS installation and configuration.
T he common FAS deployments are summarized in the Federated Authentication Service architectures overview article.
Other "how-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.432
Federated Authentication Service private key
protection
Nov 28 , 20 17
Introduction
Private keys are stored by means of the Network Service account and marked as non-exportable by default.
T here are two types of private keys:
T he private key associated with the registration authority (RA) certificate, from the Citrix_RegistrationAuthority
certificate template.
T he private keys associated with the user certificates, from the Citrix_SmartcardLogon certificate template.
T here are actually two RA certificates: Citrix_RegistrationAuthority_ManualAuthorization (valid for 24 hours by default) and
Citrix_RegistrationAuthority (valid for two years by default).
During step 3 of the Initial Setup in the FAS administration console, when the administrator clicks “Authorize” the FAS
server generates a keypair and sends a Certificate Signing Request (CSR) to the CA for the
Citrix_RegistrationAuthority_ManualAuthorization certificate. T his is a temporary certificate, valid for 24 hours by
default. T he CA does not automatically issue this certificate; its issuance must be manually authorised on the CA by an
administrator. Once the certificate is issued to the FAS server, FAS uses the
Citrix_RegistrationAuthority_ManualAuthorization certificate to automatically obtain the
Citrix_RegistrationAuthority certificate (valid for two years by default). T he FAS server deletes the certificate and key
for Citrix_RegistrationAuthority_ManualAuthorization as soon as it obtains the Citrix_RegistrationAuthority
certificate.
T he private key associated with the RA certificate is particularly sensitive, because the RA certificate policy allows whoever
possesses the private key to issue certificate requests for the set of users configured in the template. As a consequence,
whoever controls this key can connect to the environment as any of the users in the set.
You can configure the FAS server to protect private keys in a way that fits your organization’s security requirements, using
one of the following:
Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Software Key Storage Provider for both the RA
certificate and the user certificates’ private keys.
Microsoft Platform Key Storage Provider with a T rusted Platform Module (T PM) chip for the RA certificate’s private key,
and Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Software Key Storage Provider for the user
certificates’ private keys.
A Hardware Security Module (HSM) vendor’s Cryptographic Service or Key Storage Provider with the HSM device for
both the RA certificate and the user certificates’ private keys.
Private key configuration settings
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.433
Configure FAS to use one of the three options. Use a text editor to edit the
Citrix.Authentication.FederatedAuthenticationService.exe.config file. T he default location of the file is in the Program
Files\Citrix\Federated Authentication Service folder on the FAS server.
T he FAS reads the config file only when the service starts. If any values are changed, the FAS must be restarted before it
reflects the new settings.
Set the relevant values in the Citrix.Authentication.FederatedAuthenticationService.exe.config file as follows:
Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderLegacyCsp (switch between CAPI and CNG APIs)
Value
Comment
true
Use CAPI APIs
false (default)
Use CNG APIs
Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName (name of the provider to use)
Value
Comment
Microsoft Enhanced RSA and AES
Default CAPI provider
Cryptographic Provider
Microsoft Software Key Storage Provider
Default CNG Provider
Microsoft Platform Key Storage Provider
Default TPM provider. Note that TPM is not recommended for user keys. Use TPM for the RA key only. If you
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.434
plan to run your FAS server in a virtualized environment, check with your TPM and hypervisor vendor whether
virtualization is supported.
HSM_Vendor CSP/Key Storage Provider
Supplied by HSM vendor. The value differs between vendors. If you plan to run your FAS server in a virtualized
environment, check with your HSM vendor whether virtualization is supported.
Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderType (Required only in case of CAPI API)
Value
Comment
24
Default. Refers to Microsoft KeyContainerPermissionAccessEntry.ProviderType Property PROV_RSA_AES 24.
Should always be 24 unless you are using an HSM with CAPI and the HSM vendor specifies otherwise.
Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyProtection (When FAS needs to perform a private key operation, it
uses the value specified here) Controls the "exportable” flag of private keys. Allows the use of T PM key storage, if
supported by the hardware.
Value
Comment
NoProtection
Private key can be exported.
GenerateNonExportableKey
Default. Private key cannot be exported.
GenerateTPMProtectedKey
Private key will be managed using the TPM. Private key is stored via the ProviderName you specified in
ProviderName (for example, Microsoft Platform Key Storage Provider)
Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyLength (Specify size of private key in bits)
Value
Comment
2048
Default. 1024 or 4096 can also be used.
T he config file settings are represented graphically as follows (installation defaults are shown in red):
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.435
Configuration scenario examples
Example 1
T his example covers the RA certificate private key and user certificates’ private keys stored using the Microsoft Software
Key Storage Provider
T his is the default post-install configuration. No additional private key configuration is required.
Example 2
T his example shows the RA certificate private key stored in the FAS server motherboard’s hardware T PM via the Microsoft
Platform Key Storage Provider, and user certificates’ private keys stored using the Microsoft Software Key Storage
Provider.
T his scenario assumes that the T PM on your FAS server motherboard has been enabled in the BIOS according to the T PM
manufacturer’s documentation and then initialized in Windows; see https://technet.microsoft.com/engb/library/cc749022(v=ws.10).aspx.
Using PowerShell (recommended)
T he RA certificate can be requested offline using PowerShell. T his is recommended for organizations that do not want
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.436
their CA to issue a RA certificate through an online CSR. An offline RA CSR cannot be made using the FAS administration
console.
Step 1: During the initial setup of the FAS configuration using the administration console, complete only the first two
steps: “Deploy certificate templates” and “Setup Certificate Authority.”
Step 2: On your CA server, add the Certificate Templates MMC snap-in. Right-click the
Citrix_RegistrationAuthority_ManualAuthorization template and select Duplicate Template.
Select the General tab. Change the name and validity period. In this example, the name is Offline_RA and the validity period
is 2 years:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.437
Step 3: On your CA server, add the CA MMC snap-in. Right-click Certificate Templates. Select New, then click Certificate
Template to Issue. Choose the template you just created.
Step 4 : Load the following PowerShell cmdlets on the FAS server:
Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Step 5: Generate the RSA keypair inside the FAS server’s T PM and create the CSR by entering the following PowerShell
cmdlet on the FAS server. Note: Some T PMs restrict key length. T he default is key length is 2048 bits. Be sure to specify a
key length supported by your hardware.
New-FasAuthorizationCertificateRequest -UseT PM $true -address <FQDN of FAS Server>
For example:
New-FasAuthorizationCertificateRequest -UseT PM $true -address fashsm.auth.net
T he following is displayed:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.438
Notes:
T he Id GUID (in this example, “5ac3d8bd-b484-4ebe-abf8-4b2cfd62ca39”) is required in a subsequent step.
T hink of this PowerShell cmdlet as a one-time “override” that is used to generate the private key for the RA certificate.
When running this cmdlet, the values that are read from the config file when the FAS service started are checked to
determine the key length to use (the default is 2048).
Because -UseT PM is set to $true in this manual PowerShell-initiated RA certificate private key operation, the system
ignores values from the file that do not match the settings required to use a T PM.
Running this cmdlet does not change any settings in the config file.
During subsequent automatic FAS-initiated user certificate private key operations, the values that were read from the
file when the FAS service started will be used.
It is also possible to set the KeyProtection value in the config file to GenerateT PMProtectedKey when the FAS server is
issuing user certificates to generate user certificate private keys protected by the T PM.
To verify that the T PM was used to generate the keypair, look in the application log in the Windows Event viewer on the
FAS server, at the time that the keypair is generated.
Note “[T PM: True]”
Followed by:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.439
Note “Provider: [CNG] Microsoft Platform Crypto Provider”
Step 6: Copy the certificate request section into a text editor and save it to disk as a text file.
Step 7: Submit the CSR to your CA by typing the following into PowerShell on the FAS server:
certreq -submit -attrib "certificatetemplate:<certificate template from step 2>" <certificate request file from step 6>
For example:
certreq -submit -attrib "certificatetemplate:Offline_RA" C:\Users\Administrator.AUT H\Desktop\usmcertreq.txt
T he following is displayed:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.440
At this point a Certification Authority List window might appear. T he CA in this example has both http (top) and DCOM
(bottom) enrolment enabled. Select the DCOM option, if available:
After the CA has been specified, PowerShell displays the RequestID:
Step 8: On the CA server, in the CA MMC snap-in, click Pending Requests. Note the Request ID. T hen right-click the
request and choose Issue.
Step 9: Select the Issued Certificates node. Find the certificate that was just issued (the Request ID should match).
Double-click to open the certificate. Select the Details tab. Click Copy to File. T he Certificate Export Wizard launches. Click
Next . Choose the following options for the file format:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.441
T he format must be “Cryptographic Message Syntax Standard – PKCS #7 Certificates (.P7B)” and “Include all
certificates in the certification path if possible” must be checked.
Step 10: Copy the exported certificate file onto the FAS server.
Step 11: Import the RA certificate into the FAS server registry by entering the following PowerShell cmdlet on the FAS
server:
For example:
T he following is displayed:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.442
Step 12: Close the FAS administration console and then restart it.
Note that the step “Authorize this Service” has turned green, and now displays “Deauthorize this Service.” T he entry below
indicates “Authorized by: Offline CSR”
Step 13: Select the User Roles tab in the FAS administration console and edit the settings described in the main FAS article.
Note: Deauthorizing the FAS through the administration console will delete the User Rule.
Using the FAS management console
T he FAS management console cannot do offline CSR, so using it is not recommended unless your organization allows online
CSR for RA certificates.
When performing the FAS initial setup steps, after deploying certificate templates and setting up the CA, but before
authorizing the service (step 3 in the configuration sequence):
Step 1: Edit the config file by changing the following line as follows:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.443
T he file should now appear as follows:
Some T PMs restrict key length. T he default key length is 2048 bits. Be sure to specify a key length supported by your
hardware.
Step 2: Authorize the service.
Step 3: Manually issue the pending certificate request from the CA server. After the RA certificate is obtained, step 3 in the
setup sequence in the management console will be green. At this point, the RA certificate’s private key will have generated
in the T PM. T he certificate will be valid for 2 years by default.
Step 4 : Edit the config file back to the following:
Note: Although FAS can generate user certificates with T PM protected keys, the T PM hardware may be too slow for large
deployments.
Step 5: Restart the Citrix Federated Authentication Service. T his forces the service to re-read the config file and reflect the
changed values. T he subsequent automatic private key operations will affect user certificate keys; those operations will not
store the private keys in the T PM, but use the Microsoft Software Key Storage Provider.
Step 6: Select the User Roles tab in the FAS administration console and edit the settings as described in the main FAS
article.
Note: Deauthorizing the FAS through the administration console will delete the User Rule.
Example 3
T his example covers an RA certificate private key and user certificates’ private keys stored in an HSM. T his example assumes
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.444
a configured HSM. Your HSM will have a provider name, for example “HSM_Vendor’s Key Storage Provider.”
If you plan to run your FAS server in a virtualized environment, check with your HSM vendor about hypervisor support.
Step 1. During the initial setup of the FAS configuration using the administration console, complete only the first two
steps: “Deploy certificate templates” and “Setup Certificate Authority.”
Step 2: Consult your HSM vendor’s documentation to determine what your HSM’s ProviderName value should be. If your
HSM uses CAPI, the provider might be referred to in the documentation as a Cryptographic Service Provider (CSP). If your
HSM uses CNG, the provider might be referred to as a Key Storage Provider (KSP).
Step 3: Edit the config file as follows:
T he file should now appear as follows:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.445
T his scenario assumes that your HSM uses CNG, so the ProviderLegacyCsp value is set to false. If your HSM uses CAPI,
ProviderLegacyCsp value should be set to true. Consult your HSM vendor’s documentation to determine whether your HSM
uses CAPI or CNG. Also consult your HSM vendor’s documentation on supported key lengths for asymmetric RSA key
generation. In this example, the key length is set to the default of 2048 bits. Ensure that the key length you specify is
supported by your hardware.
Step 4 : Restart the Citrix Federated Authentication Service to read the values from the config file.
Step 5: Generate the RSA keypair inside the HSM and create the CSR by clicking Authorize in the Initial Setup tab of the
FAS administration console.
Step 6: To verify that the keypair was generated in the HSM, check the application entries in the Windows Event log:
Note: [Provider: [CNG] HSM_Vendor’s Key Storage Provider]
Step 7: On the CA server, in the CA MMC, select the Pending Requests node:
Right-click the request and select Issue.
Note that the step “Authorize this Service” has turned green, and now displays “Deauthorize this Service.” T he entry below
indicates “Authorized by: [<CA Name>]”
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.446
Step 8: Select the User Roles tab in the FAS administration console and edit the settings as described in the main FAS
article.
Note: Deauthorizing the FAS through the administration console will delete the User Rule.
FAS certificate storage
FAS does not use the Microsoft certificate store on the FAS server to store its certificates. It uses the registry.
Note: When using an HSM to store private keys, HSM containers are identified with a GUID. T he GUID for the private key in
the HSM matches the GUID for the equivalent certificate in the registry.
To determine the GUID for the RA certificate, enter the following PowerShell cmdlets on the FAS server:
Add-pssnapin Citrix.a*
Get-FasAuthorizationCertificate – address <FAS server FQDN>
For example:
Get-FasAuthorizationCertificate – address cg-fas-2.auth.net
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.447
To obtain a list of user certificates, enter:
Get-FasUserCertificate – address <FAS server FQDN>
For example:
Get-FasUserCertificate – address cg-fas-2.auth.net
Related information
T he Federated Authentication Service article is the primary reference for FAS installation and configuration.
T he common FAS deployments are summarized in the Federated Authentication Services architectures overview article.
Other "how-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.448
Federated Authentication Service security and
network configuration
Nov 28 , 20 17
T he Citrix Federated Authentication Service (FAS) is tightly integrated with Microsoft Active Directory and the Microsoft
certification authority (CA). It is essential to ensure that the system is managed and secured appropriately, developing a
security policy as you would for a domain controller or other critical infrastructure.
T his document provides an overview of security issues to consider when deploying the FAS. It also provides an overview of
features available that may assist in securing your infrastructure.
Network architecture
T he following diagram shows the main components and security boundaries used in an FAS deployment.
T he FAS server should be treated as part of the security-critical infrastructure, along with the CA and domain controller. In
a federated environment, Citrix NetScaler and Citrix Storefront are components that are trusted to perform user
authentication; other XenApp and XenDesktop components are unaffected by introducing the FAS.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.449
Firewall and network security
Communication between NetScaler, StoreFront and the Delivery Controller components should be protected by T LS over
port 443. T he StoreFront server performs only outgoing connections, and the NetScaler Gateway should accept only
connections over the Internet using HT T PS port 443.
T he StoreFront server contacts the FAS server over port 80 using mutually authenticated Kerberos. Authentication uses
the Kerberos HOST /fqdn identity of the FAS server, and the Kerberos machine account identity of the StoreFront server.
T his generates a single use “credential handle” needed by the Citrix Virtual Delivery Agent (VDA) to log on the user.
When an HDX session is connected to the VDA, the VDA also contacts the FAS server over port 80. Authentication uses
the Kerberos HOST /fqdn identity of the FAS server, and the Kerberos machine identity of the VDA. Additionally, the VDA
must supply the “credential handle” to access the certificate and private key.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.450
T he Microsoft CA accepts communication using Kerberos authenticated DCOM, which can be configured to use a fixed
TCP port. T he CA additionally requires that the FAS server supply a CMC packet signed by a trusted enrollment agent
certificate.
Server
Firewall Ports
Federated Authentication Service
[in] Kerberos over HT T P from StoreFront and VDAs
[out] DCOM to Microsoft CA
Netscaler
[in] HT T PS from client machines
[in/out] HT T PS to/from StoreFront server
[out] HDX to VDA
StoreFront
[in] HT T PS from NetScaler
[out] HT T PS to Delivery Controller
[out] Kerberos HT T P to FAS
Delivery Controller
[in] HT T PS from StoreFront server
[in/out] Kerberos over HT T P from VDAs
VDA
[in/out] Kerberos over HT T P from Delivery Controller
[in] HDX from NetScaler Gateway
[out] Kerberos HT T P to FAS
Microsoft CA
[in] DCOM & signed from FAS
Administration responsibilities
Administration of the environment can be divided into the following groups:
Name
Responsibility
Enterprise Administrator
Install and secure certificate templates in the forest
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.451
Domain Administrator
Configure Group Policy settings
CA Administrator
Configure the certificate authority
FAS Administrator
Install and configure the FAS server
StoreFront/Netscaler Admin
Configure user authentication
XenDesktop Administrator
Configure VDAs and Controllers
Each administrator controls different aspects of the overall security model, allowing a defense-in-depth approach to
securing the system.
Group Policy settings
Trusted FAS machines are identified by a lookup table of “index number -> FQDN” configured through Group Policy. When
contacting an FAS server, clients verify the FAS server’s HOST \<fqdn> Kerberos identity. All servers that access the FAS
server must have identical FQDN configurations for the same index; otherwise, StoreFront and VDAs may contact different
FAS servers.
To avoid misconfiguration, Citrix recommends that a single policy be applied to all machines in the environment. Take care
when modifying the list of FAS servers, especially when removing or reordering entries.
Control of this GPO should be limited to FAS administrators (and/or domain administrators) who install and decommission
FAS servers. Take care to avoid reusing a machine FQDN name shortly after decommissioning an FAS server.
Certificate templates
If you do not want to use the Citrix_SmartcardLogon certificate template supplied with the FAS, you can modify a copy of
it. T he following modifications are supported.
Rename a certificate template
If you want to rename the Citrix_SmartcardLogon to match your organizational template naming standard, you must:
Create a copy of the certificate template and rename it to match your organizational template naming standard.
Use FAS PowerShell commands to administer FAS, rather than the administrative user interface. (T he administrative user
interface is only intended for use with the Citrix default template names.)
Either use the Microsoft MMC Certificate T emplates snap-in or the Publish-FasMsT emplate command to publish your
template, and
Use the New-FasCertificateDefinition command to configure FAS with the name of your template.
Modif y General properties
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.452
You can modify the Validity period in the certificate template.
Do not modify the Renewal period. FAS ignores this setting in the certificate template. FAS automatically renews the
certificate halfway through its validity period.
Modif y Request Handling properties
Do not modify these properties. FAS ignores these settings in the certificate template. FAS always deselects Allow private
key to be exported and deselects Renew with same key.
Modif y Cryptography properties
Do not modify these properties. FAS ignores these settings in the certificate template.
Refer to Federated Authentication Service private key protection for equivalent settings that FAS provides.
Modif y Key Attestation properties
Do not modify these properties. FAS does not support key attestation.
Modif y Superseded Templates properties
Do not modify these properties. FAS does not support superseding templates.
Modif y Extensions properties
You can modify these settings to match your organizational policy.
Note: Inappropriate Extension settings may cause security issues, or result in unusable certificates.
Modif y Security properties
Citrix recommends that you modify these settings to Allow the Enroll permission for only the machine accounts of the FAS
servers. As for other services, also Allow the Full Control permission for SYST EM. No other permissions are required. You
may want to Allow other permissions, for example to allow FAS administrators to view a modified template for
troubleshooting purposes.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.453
Modif y Subject Name properties
You can modify these settings to match your organizational policy, if needed.
Modif y Server properties
Although Citrix does not recommend it, you can modify these settings to match your organizational policy, if needed.
Modif y Issuance requirements properties
Do not modify these settings. T hese settings should be as shown:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.454
Modif y Compatibility properties
You can modify these settings. T he setting must be at least Windows Server 2003 CAs (schema version 2). However, FAS
supports only Windows Server 2008 and later CAs. Also, as explained above, FAS ignores the additional settings available by
selecting Windows Server 2008 CAs (schema version 3) or Windows Server 2012 CAs (schema version 4).
Certificate authority administration
T he CA administrator is responsible for the configuration of the CA server and the issuing certificate private key that it uses.
Publishing templates
For a certificate authority to issue certificates based on a template supplied by the enterprise administrator, the CA
administrator must choose to publish that template.
A simple security practice is to publish only the RA certificate templates when the FAS servers are being installed, or to insist
on a completely offline issuance process. In either case, the CA administrator should maintain complete control over
authorizing RA certificate requests, and have a policy for authorizing FAS servers.
Firewall settings
Generally, the CA administrator will also have control of the network firewall settings of the CA, allowing control over
incoming connections. T he CA administrator can configure DCOM TCP and firewall rules so that only FAS servers can
request certificates.
Restricted enrollment
By default any holder of an RA certificate can issue certificates to any user, using any certificate template that allows
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.455
access. T his should be restricted to a group of non-privileged users using the “Restrict enrollment agents” CA property.
Policy modules and auditing
For advanced deployments, custom security modules can be used to track and veto certificate issuance.
FAS administration
T he FAS has several security features.
Restrict StoreFront , users, and VDAs through an ACL
At the center of the FAS security model is the control for which Kerberos accounts can access functionality:
Access Vector
Description
StoreFront [IdP]
T hese Kerberos accounts are trusted to declare that a user has been correctly
authenticated. If one of these accounts is compromised, then certificates can be created
and used for users allowed by the configuration of the FAS.
VDAs [Relying party]
T hese are the machines that are allowed to access the certificates and private keys. A
credential handle retrieved by the IdP is also needed, so a compromised VDA account in this
group has limited scope to attack the system.
Users
T his controls which users can be asserted by the IdP. Note that there is overlap with the
“Restricted Enrollment Agent” configuration options at the CA.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.456
In general, it is advisable to include only non-privileged accounts in this list. T his prevents a
compromised StoreFront account from escalating privileges to a higher administrative level.
In particular, domain administrator accounts should not be allowed by this ACL.
Configure rules
Rules are useful if multiple independent XenApp or XenDesktop deployments use the same FAS server infrastructure. Each
rule has a separate set of configuration options; in particular, the ACLs can be configured independently.
Configure the CA and templates
Different certificate templates and CAs can be configured for different access rights. Advanced configurations may
choose to use less or more powerful certificates, depending on the environment. For example, users identified as “external”
may have a certificate with fewer privileges than “internal” users.
In-session and authentication certificates
T he FAS administrator can control whether the certificate used to authenticate is available for use in the user’s session.
For example, this could be used to have only “signing” certificates available in-session, with the more powerful “logon”
certificate being used only at logon.
Private key protection and key length
T he FAS administrator can configure FAS to store private keys in a Hardware Security Module (HSM) or Trusted Platform
Module (T PM). Citrix recommends that at least the RA certificate private key is protected by storing it in a T PM; this option
is provided as part of the “offline” certificate request process.
Similarly, user certificate private keys can be stored in a T PM or HSM. All keys should be generated as “non-exportable” and
be at least 2048 bits in length.
Event logs
T he FAS server provides detailed configuration and runtime event logs, which can be used for auditing and intrusion
detection.
Administrative access and administration tools
T he FAS includes remote administration features (mutually authenticated Kerberos) and tools. Members of the “Local
Administrators Group” have full control over FAS configuration. T his list should be carefully maintained.
XenApp, XenDesktop, and VDA administrators
In general, the use of the FAS doesn’t change the security model of the Delivery Controller and VDA administrators, as the
FAS “credential handle” simply replaces the “Active Directory password.” Controller and VDA administration groups should
contain only trusted users. Auditing and event logs should be maintained.
General Windows server security
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.457
All servers should be fully patched and have standard firewall and anti-virus software available. Security-critical
infrastructure servers should be kept in a physically secure location, with care taken over disk encryption and virtual machine
maintenance options.
Auditing and event logs should be stored securely on a remote machine.
RDP access should be limited to authorized administrators. Where possible, user accounts should require smart card logon,
especially for CA and domain administrator accounts.
Related information
T he Federated Authentication Service article is the primary reference for FAS installation and configuration.
FAS architectures are introduced in the Federated Authentication Service architectures overview article.
Other "how-to" articles are introduced in the Federated Authentication Service configuration and management article.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.458
Federated Authentication Service troubleshoot
Windows logon issues
Nov 28 , 20 17
In this article:
Certificates and public key infrastructure
UPN name and certificate mapping
Control logon domain controller selection
Enable account audit events
Certificate validation logs
Kerberos logs
Event log messages
End user error messages
Related information
T his article describes the logs and error messages Windows provides when a user logs on using certificates and/or smart
cards. T hese logs provide information you can use to troubleshoot authentication failures.
Certificates and public key infrastructure
Windows Active Directory maintains several certificate stores that manage certificates for users logging on.
NTAuth certif icate store: T o authenticate to Windows, the CA immediately issuing user certificates (that is, no
chaining is supported) must be placed in the NT Auth store. T o see these certificates, from the certutil program, enter:
certutil – viewstore – enterprise NT Auth.
Root and intermediate certif icate stores: Usually, certificate logon systems can provide only a single certificate, so if
a chain is in use, the intermediate certificate store on all machines must include these certificates. T he root certificate
must be in the T rusted Root Store, and the penultimate certificate must be in the NT Auth store.
Logon certif icate extensions and Group Policy: Windows can be configured to enforce verification of EKUs and
other certificate policies. See the Microsoft documentation: https://technet.microsoft.com/enus/library/ff404287%28v=ws.10%29.aspx.
Registry policy
Description
AllowCertificatesWithNoEKU
When disabled, certificates must include the smart card logon
Extended Key Usage (EKU).
AllowSignatureOnlyKeys
By default, Windows filters out certificates private keys that do
not allow RSA decryption. T his option overrides that filter.
AllowT imeInvalidCertificates
By default, Windows filters out expired certificates. T his option
overrides that filter.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.459
EnumerateECCCerts
Enables elliptic curve authentication.
X509HintsNeeded
If a certificate does not contain a unique User Principal Name
(UPN), or it could be ambiguous, this option allows users to
manually specify their Windows logon account.
UseCachedCRLOnlyAnd
Disables revocation checking (usually set on the domain
IgnoreRevocationUnknownErrors
controller).
Domain controller certif icates: T o authenticate Kerberos connections, all servers must have appropriate “Domain
Controller” certificates. T hese can be requested using the “Local Computer Certificate Personal Store” MMC snap-in
menu.
UPN name and certificate mapping
It is recommended that user certificates include a unique User Principal Name (UPN) in the Subject Alternate Name
extension.
UPN names in Active Directory
By default, every user in Active Directory has an implicit UPN based on the pattern <samUsername>@<domainNetBios> and
<samUsername>@<domainFQDN>. T he available domains and FQDNs are included in the RootDSE entry for the forest.
Note that a single domain can have multiple FQDN addresses registered in the RootDSE.
Additionally, every user in Active Directory has an explicit UPN and altUserPrincipalNames. T hese are LDAP entries that
specify the UPN for the user.
When searching for users by UPN, Windows looks first in the current domain (based on the identity of the process looking
up the UPN) for explicit UPNs, then alterative UPNs. If there are no matches, it looks up the implicit UPN, which may resolve
to different domains in the forest.
Certificate Mapping Service
If a certificate does not include an explicit UPN, Active Directory has the option to store an exact public certificate for each
use in an “x509certificate” attribute. To resolve such a certificate to a user, a computer can query for this attribute directly
(by default, in a single domain).
An option is provided for the user to specify a user account that speeds up this search, and also allows this feature to be
used in a cross-domain environment.
If there are multiple domains in the forest, and the user does not explicitly specify a domain, the Active Directory rootDSE
specifies the location of the Certificate Mapping Service. T his is usually located on a global catalog machine, and has a
cached view of all x509certificate attributes in the forest. T his computer can be used to efficiently find a user account in
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.460
any domain, based on only the certificate.
Control logon domain controller selection
When an environment contains multiple domain controllers, it is useful to see and restrict which domain controller is used
for authentication, so that logs can be enabled and retrieved.
Control domain controller selection
To force Windows to use a particular Windows domain controller for logon, you can explicitly set the list of domain
controllers that a Windows machine uses by configuring the lmhosts file: \Windows\System32\drivers\etc\lmhosts.
T here is usually a sample file named “lmhosts.sam” in that location. Simply include a line:
1.2.3.4 dcnetbiosname #PRE #DOM:mydomai
Where "1.2.3.4" is the IP address of the domain controller named "dcnetbiosname" in the "mydomain" domain.
After a restart, the Windows machine uses that information to log on to mydomain. Note that this configuration must be
reverted when debugging is complete.
Identif y the domain controller in use
At logon, Windows sets an MSDOS environment variable with the domain controller that logged the user on. To see this,
start the command prompt with the command: echo %LOGONSERVER%.
Logs relating to authentication are stored on the computer returned by this command.
Enable account audit events
By default, Windows domain controllers do not enable full account audit logs. T his can be controlled through audit policies
in the security settings in the Group Policy editor. After they are enabled, the domain controller produces extra event log
information in the security log file.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.461
Certificate validation logs
Check certificate validity
If a smartcard certificate is exported as a DER certificate (no private key required), you can validate it with the command:
certutil – verify user.cer
Enable CAPI logging
On the domain controller and users machine, open the event viewer and enable logging for
Microsoft/Windows/CAPI2/Operational Logs.
You can control CAPI logging with the registry keys at: CurrentControlSet\Services\crypt32.
Value
Description
DiagLevel (DWORD)
Verbosity level (0 to 5)
DiagMatchAnyMask (QUADWORD)
Event filter (use 0xffffff for all)
DiagProcessName (MULT I_SZ)
Filter by process name (for example, LSASS.exe)
CAPI logs
Message
Description
Build Chain
LSA called CertGetCertificateChain (includes result)
Verify Revocation
LSA called CertVerifyRevocation (includes result)
X509 Objects
In verbose mode, certificates and Certificate Revocation Lists (CRLs) are dumped to
AppData\LocalLow\Microsoft\X509Objects
Verify Chain Policy
LSA called CertVerifyChainPolicy (includes parameters)
Error messages
Error code
Description
Certificate not trusted
T he smart card certificate could not be built using
certificates in the computer's intermediate and trusted
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.462
root certificate stores.
Certificate revocation check error
T he CRL for the smart card could not be downloaded
from the address specified by the certificate CRL
distribution point. If revocation checking is mandated, this
prevents logon from succeeding. See the Certificates and
public key infrastructure section.
Certificate Usage errors
T he certificate is not suitable for logon. For example, it
might be a server certificate or a signing certificate.
Kerberos logs
To enable Kerberos logging, on the domain controller and the end user machine, create the following registry values:
Hive
Value name
Value [DWORD]
CurrentControlSet\Control\Lsa\Kerberos\Parameters
LogLevel
0x1
CurrentControlSet\Control\Lsa\Kerberos\Parameters
KerbDebuglevel
0xffffffff
CurrentControlSet\Services\Kdc
KdcDebugLevel
0x1
CurrentControlSet\Services\Kdc
KdcExtraLogLevel
0x1f
Kerberos logging is output to the System event log.
Messages such as “untrusted certificate” should be easy to diagnose.
T wo error codes are informational, and can be safely ignored:
KDC_ERR_PREAUT H_REQUIRED (used for backward compatibility with older domain controllers)
Unknown error 0x4b
Event log messages
T his section describes the expected log entries on the domain controller and workstation when the user logs on with a
certificate.
Domain controller CAPI2 log
Domain controller security logs
VDA security log
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.463
VDA CAPI log
VDA system log
Domain controller CAPI2 log
During a logon, the domain controller validates the caller’s certificate, producing a sequence of log entries in the following
form.
T he final event log message shows lsass.exe on the domain controller constructing a chain based on the certificate
provided by the VDA, and verifying it for validity (including revocation). T he result is returned as “ERROR_SUCCESS”.
Domain controller security log
T he domain controller shows a sequence of logon events, the key event being 4768, where the certificate is used to issue
the Kerberos T icket Granting T icket (krbtgt).
T he messages before this show the machine account of the server authenticating to the domain controller. T he messages
following this show the user account belonging to the new krbtgt being used to authenticate to the domain controller.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.464
VDA security log
T he VDA security audit log corresponding to the logon event is the entry with event ID 4648, originating from
winlogon.exe.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.465
VDA CAPI log
T his example VDA CAPI log shows a single chain build and verification sequence from lsass.exe, validating the domain
controller certificate (dc.citrixtest.net).
VDA system log
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.466
When Kerberos logging is enabled, the system log shows the error KDC_ERR_PREAUT H_REQUIRED (which can be ignored),
and an entry from Winlogon showing that the Kerberos logon was successful.
End user error messages
T his section lists common error messages displayed to a user on the Windows logon page.
Error message displayed
Description and reference
Invalid Username or Password
T he computer believes that you have a valid certificate
and private key, but the Kerberos domain controller has
rejected the connection. See the Kerberos logs section of
this article.
T he system could not log you on. Your credentials could
T he domain controller cannot be contacted, or the
not be verified.
domain controller does not have appropriate certificates
installed.
Re-enroll the “Domain Controller” and “Domain Controller
T he request is not supported
Authentication” certificates on the domain controller, as
described in CT X206156. T his is usually worth trying, even
when the existing certificates appear to be valid.
T he system could not log you on. T he smartcard
T he intermediate and root certificates are not installed on
certificate used for authentication was not trusted.
the local computer. See CT X206156 for instructions on
installing smart card certificates on non-domain joined
computers. Also, see the Certificates and public key
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.467
infrastructure section in this article.
You cannot logon because smart card logon is not
A workgroup user account has not been fully configured
supported for your account.
for smart card logon.
T he requested key does not exist
A certificate references a private key that is not
accessible. T his can happen when a PIV card is not
completely configured and is missing the CHUID or CCC
file.
An error occurred when trying to use the smart card
T he smart card middleware was not installed correctly.
See CT X206156 for smart card installation instructions.
Insert a smart card
T he smart card or reader was not detected. If the smart
card is inserted, this message indicates a hardware or
middleware issue. See CT X206156 for smart card
installation instructions.
T he PIN is incorrect
T he smart card rejected a PIN entered by the user.
No valid smart card certificate could be found.
T he extensions on the certificate might not be set
correctly, or the RSA key is too short (<2048 bits). See
CT X206901 for information about generating valid smart
card certificates.
T he smart card is blocked
A smart card has been locked (for example, the user
entered an incorrect pin multiple times).
An administrator may have access to the pin unlock (puk)
code for the card, and can reset the user pin using a tool
provided by the smart card vendor.
If the puk code is not available, or locked out, the card
must be reset to factory settings.
Bad Request
A smart card private key does not support the
cryptography required by the domain controller. For
example, the domain controller might have requested a
“private key decryption,” but the smart card supports only
signing.
T his usually indicates that the extensions on the
certificate are not set correctly, or the RSA key is too
short (<2048 bits). See CT X206901 for information about
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.468
generating valid smart card certificates.
Related information
Configuring a domain for smart card logon: http://support.citrix.com/article/CT X206156
Smartcard logon policies: https://technet.microsoft.com/en-us/library/ff404287%28v=ws.10%29.aspx
Enabling CAPI logging: http://social.technet.microsoft.com/wiki/contents/articles/242.troubleshooting-pki-problems-onwindows.aspx
Enabling Kerberos logging: https://support.microsoft.com/en-us/kb/262177
Guidelines for enabling smart card logon with third-party certification authorities: https://support.microsoft.com/enus/kb/281245
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.469
Federated Authentication Service PowerShell cmdlets
Nov 28 , 20 17
You can use the Federated Authentication Service administration console for simple deployments; however, the PowerShell
interface offers more advanced options. If you plan to use options that are not available in the console, Citrix recommends
using only PowerShell for configuration.
T he following command adds the FAS PowerShell cmdlets:
Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
In a PowerShell window, you can use Get-Help <cmdlet name> to display cmdlet help.
T he zip file linked below contains help files for all FAS PowerShell SDK cmdlets. To use it, click the link, which will download
the zip file. T hen extract its content to a local folder. T he index.html file lists all cmdlets, with links to individual cmdlet help
files.
ZIP
Federated Authentication Service PowerShell cmdlet help files
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.470
Graphics
Nov 28 , 20 17
Citrix HDX graphics include an extensive set of graphics acceleration and encoding technologies that optimizes the delivery
of rich graphics applications from XenApp and XenDesktop. T he graphic technologies provide the same experience as using
a physical desktop when working remotely with virtual applications that are graphics intensive.
You can use software or hardware for graphics rendering. Software rendering requires a third-party library called software
rasterizer. For example, Windows includes the WARP rasterizer for DirectX based graphics. Sometimes, you might want to
use an alternative software renderer (for example, OpenGL Software Accelerator). Hardware rendering (hardware
acceleration) requires a graphics processor (GPU).
HDX Graphics offers a default encoding configuration that is optimized for the most common use cases. By using Citrix
policies, IT administrators can also configure various graphics-related settings to meet different requirements and provide
the desired user experience.
Thinwire
T hinwire is the Citrix default display remoting technology used in XenApp and XenDesktop.
Display remoting technology allows graphics generated on one machine to be transmitted, typically across a network, to
another machine for display. Graphics are generated as a result of user input, for example, keystrokes or mouse actions.
HDX 3D Pro
T he HDX 3D Pro capabilities in XenApp and XenDesktop enable you to deliver desktops and applications that perform best
using a graphics processing unit (GPU) for hardware acceleration. T hese applications include 3D professional graphics
applications based on OpenGL and DirectX. T he standard VDA supports GPU acceleration of DirectX only.
GPU acceleration f or Windows desktop OS
By using HDX 3D Pro, you can deliver graphically intensive applications as part of hosted desktops or applications on
Desktop OS machines. HDX 3D Pro supports physical host computers (including desktop, blade, and rack workstations) and
GPU Passthrough and GPU virtualization technologies offered by XenServer, vSphere, and Hyper-V (passthrough only)
hypervisors.
Using GPU Passthrough, you can create VMs that have exclusive access to dedicated graphics processing hardware. You can
install multiple GPUs on the hypervisor and assign VMs to each of these GPUs on a one-to-one basis.
Using GPU virtualization, multiple virtual machines can directly access the graphics processing power of a single physical GPU.
GPU acceleration f or Windows server OS
HDX 3D Pro allows graphics-heavy applications running in Windows Server OS sessions to render on the server graphics
processing unit (GPU). By moving OpenGL, DirectX, Direct3D, and Windows Presentation Foundation (WPF) rendering to the
server GPU, graphics rendering doesn't slow down the server CPU. Also, the server is able to process more graphics because
the workload is split among the CPU and GPU.
Framehawk
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.471
Framehawk is a display remoting technology for mobile workers on broadband wireless connections (Wi-Fi and 4G/LT E
cellular networks). Framehawk overcomes the challenges of spectral interference and multipath propagation, delivering a
fluid and interactive user experience to users of virtual apps and desktops.
OpenGL Sof tware Accelerator
T he OpenGL Software Accelerator is a software rasterizer for OpenGL applications such as ArcGIS, Google Earth, Nehe,
Maya, Blender, Voxler, computer-aided design, and computer-aided manufacturing. Sometimes, the OpenGL Software
Accelerator can eliminate the need to use graphics cards to deliver a good user experience with OpenGL applications.
Related information
T hinwire
HDX 3D Pro
GPU acceleration for Windows Desktop OS
GPU acceleration for Windows Server OS
Framehawk
OpenGL Software Accelerator
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.472
Framehawk
Jan 11, 20 18
Framehawk is a specialized display remoting technology for mobile workers on broadband wireless connections (Wi-Fi and
4G/LT E cellular networks) subject to high packet loss. Framehawk overcomes the challenges of spectral interference and
multipath propagation, delivering a fluid and interactive user experience to users of virtual apps and desktops on Windows
and iOS mobile devices such as laptops and tablets. To maximize server scalability and minimize network bandwidth
consumption, we recommend using Framehawk only for the specific use case described above. We recommend adaptive
transport, which incorporates many Framehawk concepts to maximize data throughput, for all other use cases.
You can use Citrix policy templates to implement Framehawk for a set of users and access scenarios in a way that is
appropriate for your organization. Framehawk targets single-screen mobile use cases such as laptops and tablets. Use
Framehawk where the business value of real time interactive performance justifies the extra cost in server resources and
the requirement for a broadband connection.
How Framehawk maintains a smooth user experience
T hink of Framehawk as a software implementation of the human eye, looking at what's in the frame buffer and discerning
the different types of content on the screen. What's important to the user? When areas of the screen are changing
rapidly, like video or moving graphics, it doesn't matter to the human eye if some pixels are lost because they are quickly
overwritten with new data.
But when it comes to static areas of the screen, such as the icons in the notification area or a toolbar, or text after
scrolling to where the user wants to start reading, the human eye is fussy. A user expects those areas to be pixel perfect.
Unlike protocols aiming to be technically accurate from a ones and zeros perspective, Framehawk aims to be relevant to
the human being who is using the technology.
Framehawk includes a next-generation Quality of Service signal amplifier plus a time-based heat map for a finer-grained and
more efficient identification of workloads. It uses autonomic, self-healing transforms in addition to data compression, and
avoids retransmission of data to maintain click response, linearity, and a consistent cadence. On a lossy network
connection, Framehawk can hide loss with interpolation, and the user still perceives good image quality while enjoying a
more fluid experience. In addition, Framehawk algorithms intelligently distinguish between different types of packet loss.
For example, random loss (send more data to compensate) versus congestion loss (don't send more data because the
channel is already clogged).
T he Framehawk Intent Engine in Citrix Receiver distinguishes between scrolling up or down, zooming, moving to the left or
right, reading, typing, and other common actions. T he engine also manages the communication back to the Virtual Delivery
Agent (VDA) using a shared dictionary. If the user is trying to read, the visual quality of the text must be excellent. If the
user is scrolling, it must be quick and smooth. And it has to be interruptible, so that the user is always in control of the
interaction with the application or desktop.
By measuring cadence on the network connection (gearing, analogous to tension on a bicycle chain), the Framehawk logic
reacts more quickly, providing a superior experience over high latency connections. T his unique and patented gearing system
provides constant up-to-date feedback on network conditions, allowing Framehawk to react immediately to changes in
bandwidth, latency, and loss.
Design considerations using Thinwire and Framehawk
Framehawk uses a data transport layer built on top of (User Datagram Protocol (UDP). UDP is a small part of how
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.473
Framehawk overcomes lossiness, as you can see when comparing the performance of Framehawk with other UDP-based
protocols. UDP provides an important foundation to the human-centric techniques that set Framehawk apart.
How much bandwidth does Framehawk require?
T he meaning of broadband wireless depends on several factors, including how many users are sharing the connection, the
quality of the connection, and apps being used. For optimal performance, Citrix suggests a base of 4 Mbps or 5 Mbps plus
about 150 Kbps per concurrent user.
Our bandwidth recommendation for T hinwire is generally a base of 1.5 Mbps plus 150 Kbps per user. For details, see the
XenApp and XenDesktop bandwidth blog). At 3% packet loss, you will find that T hinwire over TCP needs much more
bandwidth than Framehawk to maintain a positive user experience.
T hinwire remains the primary display remoting channel in the ICA protocol. Framehawk is disabled by default. Citrix
recommends enabling it selectively to address the broadband wireless access scenarios in your organization. Remember that
Framehawk requires considerably more server resources (CPU and memory) than T hinwire.
Requirements and considerations
Framehawk requires minimum VDA 7.6.300 and Group Policy Management 7.6.300.
T he endpoint must have a minimum Citrix Receiver for Windows 4.3.100 or Citrix Receiver for iOS 6.0.1.
By default, Framehawk uses a bidirectional User Datagram Protocol (UDP) port range (3224-3324) to exchange Framehawk
display channel data with Citrix Receiver. T he range can be customized in a policy setting called Framehawk display
channel port range. Each concurrent connection between the client and the virtual desktop requires a unique port. For
multi-user OS environments, such as XenApp servers, define sufficient ports to support the maximum number of concurrent
user sessions. For a single-user OS, such as VDI desktops, it is sufficient to define a single UDP port. Framehawk attempts
to use the first defined port, working up to the final port specified in the range. T his applies both when passing through
NetScaler Gateway, and internal connections directly to the StoreFront server.
For remote access, a NetScaler Gateway must be deployed. By default, NetScaler uses UDP port 443 for encrypted
communication between the client Citrix Receivers and the Gateway. T his port must be open on any external firewalls to
allow secure communication in both directions. T he feature is known as Datagram Transport Security (DT LS).
Note: Framehawk/DT LS connections are not supported on FIPS appliances.
Encrypted Framehawk connections are supported, starting with NetScaler Gateway version 11.0.62 and NetScaler Unified
Gateway version 11.0.64.34 or later.
NetScaler High Availability (HA) is supported from XenApp and XenDesktop 7.12.
Consider the following best practices before implementing Framehawk:
Contact your Security administrator to confirm UDP ports defined for Framehawk are open on the firewall. T he
installation process does not automatically configure the firewall.
Often, NetScaler Gateway might be installed in the DMZ, flanked by firewalls on both the external and the internal side.
Ensure UDP port 443 is open on the external firewall. Ensure UDP ports 3224-3324 are open on the internal firewall if
the environment is using the default port ranges.
Configuration
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.474
Caution: Citrix recommends that you enable Framehawk only for users who are likely to experience high packet loss. We
also recommend that you do not enable Framehawk as a universal policy for all objects in the Site.
Framehawk is disabled by default. When enabled, the server attempts to use Framehawk for user graphics and input. If the
prerequisites are not met for any reason, the connection is established using the default mode (T hinwire).
T he following policy settings affect Framehawk:
Framehawk display channel: Enables or disables the feature.
Framehawk display channel port range: Specifies the range of UDP port numbers (lowest port number to highest) that
the VDA uses to exchange Framehawk display channel data with the user device. T he VDA attempts to use each port,
starting at the lowest port number and incrementing for each subsequent attempt. T he port handles inbound and
outbound traffic.
Opening ports f or the Framehawk display channel
From XenApp and XenDesktop 7.8, an option is available to reconfigure the Firewall during the Features step of the VDA
installer. T his check box opens UDP ports 3224-3324 on the Windows Firewall, if selected. Manual Firewall configuration is
required in some circumstances:
For any network Firewalls.
or
T he default port range is customized.
To open these UDP ports, select the Framehawk check box:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.475
You can also use the command line to open UDP ports for Framehawk using /ENABLE_FRAMEHAWK_PORT:
Verifying Framehawk UDP port assignments
During installation, you can verify the UDP ports assigned to Framehawk in the Firewall screen:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.476
T he Summary screen indicates if the Framehawk feature is enabled:
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.477
NetScaler Gateway support f or Framehawk
Encrypted Framehawk traffic is supported on NetScaler Gateway 11.0.62.10 or later, and NetScaler Unified Gateway
11.0.64.34 or later.
NetScaler Gateway refers to the deployment architecture where the Gateway VPN vServer is directly accessible from
the end user device. T hat is, the VPN vServer has a public IP address assigned and the user connects to this IP address
directly.
NetScaler with Unified Gateway refers to the deployment where the Gateway VPN vServer is bound as a target to the
Content Switching vServer (CS). In this deployment, CS vServer has the public internet protocol address and the Gateway
VPN vServer has a dummy internet protocol address.
To enable Framehawk support on NetScaler Gateway, the DT LS parameter on the Gateway VPN vServer level must be
enabled. After the parameter is enabled and the components on XenApp or XenDesktop are updated correctly, Framehawk
audio, video, and interactive traffic is encrypted between the Gateway VPN vServer and the user device.
NetScaler Gateway, Unified Gateway, and NetScaler Gateway + global server load balancing are supported with
Framehawk.
T he following scenarios are not supported with Framehawk:
HDX Insight
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.478
NetScaler Gateway in IPv6 mode
NetScaler Gateway Double Hop
NetScaler Gateway with Cluster setup
Scenario
Framehawk support
NetScaler Gateway
Yes
NetScaler + global server load balancing
Yes
Yes
NetScaler with Unified Gateway
Note: Unified Gateway version 11.0.64.34 and later is
supported.
HDX Insight
No
NetScaler Gateway in IPv6 mode
No
NetScaler Gateway Double Hop
No
Multiple Secure T icket Authority (ST A) on NetScaler
Gateway
Yes
NetScaler Gateway and High Availability (HA)
Yes
NetScaler Gateway and Cluster setup
No
Configuring NetScaler f or Framehawk support
To enable Framehawk support on NetScaler Gateway, enable the DT LS parameter on the Gateway VPN vServer level. After
the parameter is enabled and the components on XenApp or XenDesktop are updated correctly, Framehawk audio, video,
and interactive traffic is encrypted between the Gateway VPN vServer and the user device.
T his configuration is required if you are enabling UDP encryption on NetScaler Gateway for remote access.
When configuring NetScaler for Framehawk support:
Ensure UDP port 443 is open on any external firewalls
Ensure CGP port (default 2598) is open on any external firewalls
Enable DT LS in the settings for the VPN virtual server
Unbind and rebind the SSL cert-key pair. T his step is not required if you are using NetScaler version 11.0.64.34 or later.
To configure NetScaler Gateway for Framehawk support:
1. Deploy and configure NetScaler Gateway to communicate with StoreFront and authenticate users for XenApp and
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.479
XenDesktop.
2. In the NetScaler Configuration tab, expand NetScaler Gateway, and select Virtual Servers.
3. Click Edit to display Basic Settings for the VPN Virtual Server; verify the state of the DT LS setting.
4. Click More to display more configuration options:
5. Select DTLS to provide communications security for datagram protocols such as Framehawk. Click OK. T he Basic
Settings area for the VPN Virtual Server shows that the DT LS flag is set to True.
6. Reopen the Server Certificate Binding screen, and click + to bind the certificate key pair.
7. Choose the certificate key pair from earlier, click Select.
8. Save the changes to the server certificate binding.
9. After saving, the certificate key pair appears. Click Bind.
10. Ignore the No usable ciphers conf igured on the SSL vserver/service warning message, if it appears.
Steps for older NetScaler Gateway versions
If you are using a version of NetScaler Gateway older than 11.0.64.34:
1. Reopen the Server Certificate Binding screen, and click + to bind the certificate key pair.
2. Choose the certificate key pair from earlier, click Select.
3. Save the changes to the server certificate binding.
4. After saving, the certificate key pair appears. Click Bind.
5. Ignore the No usable ciphers conf igured on the SSL vserver/service warning message, if it appears.
To configure Unified Gateway for Framehawk support:
1. Ensure that Unified Gateway is installed and properly configured. For additional information, see Unified Gateway
information on the Citrix Product Documentation site.
2. Enable the DT LS parameter on the VPN vServer, which is bound to CS vServer as T arget vServer.
Limitations
If there are stale DNS entries for the NetScaler Gateway virtual server on the client device, adaptive transport and
Framehawk might fall back to TCP transport instead of UDP transport. If fallback to TCP transport occurs, flush the DNS
cache on the client and reconnect to establish the session using UDP transport.
Framehawk doesn't support 32-bit mouse cursors, as found in applications such as PTC Creo.
Framehawk is designed for mobile devices such as laptops and tablets using a single monitor, and it reverts to T hinwire in a
dual/multi-monitor configuration.
Support f or other VPN products
NetScaler Gateway is the only SSL VPN product to support the UDP encryption required by Framehawk. If another SSL
VPN or an incorrect version of NetScaler Gateway is used, the Framehawk policy might fail to apply. Traditional IPsec VPN
products support Framehawk without any modifications.
Monitoring Framehawk
You can monitor the use and performance of Framehawk from Citrix Director. T he HDX Virtual Channel Details view
contains useful information for troubleshooting and monitoring Framehawk in any session. To view Framehawk related
metrics, select Graphics-Framehawk.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.480
If the Framehawk connection is established, you see Provider = VD3D and Connected = True in the details page. It is
normal for the virtual channel state to be idle, because it monitors the signaling channel, which is used only during the initial
handshake. T his page also provides other useful statistics about the connection.
If you encounter issues, see the Framehawk troubleshooting blog.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.481
HDX 3D Pro
Nov 28 , 20 17
T he HDX 3D Pro capabilities of XenApp and XenDesktop enable you to deliver desktops and applications that perform best
using a graphics processing unit (GPU) for hardware acceleration. T hese applications include 3D professional graphics
applications based on OpenGL and DirectX. T he standard VDA supports GPU acceleration of DirectX only.
When you install a VDA on a desktop OS, the VDA evaluates criteria and sets the mode automatically. If a supported GPU is
available, the VDA configures itself to use the GPU and HDX 3D Pro for graphics rendering and encoding. Otherwise, the
graphics subsystem deploys Citrix Virtual Displays in a standard VDA mode. For clients with multiple monitors, we support a
mixture of both supported GPUs on the VDA and Citrix Virtual Displays at the same time.
For the HDX 3D Pro policy settings, see "Optimize for 3D graphics workload" and "Display lossless indicator" in Graphics
policy settings.
All supported Citrix Receivers can be used with 3D graphics. For best performance with complex 3D workloads, highresolution monitors, multi-monitor configurations, and high frame rate applications, we recommend the latest versions of
Citrix Receiver for Windows and Citrix Receiver for Linux. For more information on supported versions of Citrix Receiver, see
Lifecycle Milestones for Citrix Receiver.
Examples of 3D professional applications include:
Computer-aided design, manufacturing, and engineering (CAD/CAM/CAE) applications
Geographical Information System (GIS) software
Picture Archiving Communication System (PACS) for medical imaging
Applications using the latest OpenGL, DirectX, NVIDIA CUDA, and OpenCL and WebGL versions
Computationally intensive non-graphical applications that use NVIDIA Compute Unified Device Architecture (CUDA) GPUs
for parallel computing
HDX 3D Pro provides the best user experience over any bandwidth:
On WAN connections: Deliver an interactive user experience over WAN connections with bandwidths as low as 1.5 Mbps.
On LAN connections: Deliver a user experience equivalent to that of a local desktop on LAN connections.
You can replace complex and expensive workstations with simpler user devices by moving the graphics processing into
the data center for centralized management.
HDX 3D Pro provides GPU acceleration for Windows Desktop OS machines and Windows Server OS machines. For more
information, see GPU acceleration for Windows Desktop OS and GPU acceleration for Windows Server OS.
HDX 3D Pro is compatible with GPU passthrough and GPU virtualization technologies offered by the following hypervisors,
in addition to bare metal:
Citrix XenServer
GPU passthrough with NVIDIA GRID and Intel GVT -d
GPU virtualization with NVIDIA GRID and Intel GVT -g
Microsoft Hyper V
GPU passthrough (Discrete Device Assignment) with NVIDIA GRID and AMD
VMware vSphere
GPU passthrough (vDGA) with NVIDIA GRID, Intel, and AMD IOMMU
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.482
GPU virtualization with NVIDIA GRID and AMD MxGPU
For the supported XenServer versions, see Citrix XenServer Hardware Compatibility List.
Use the HDX Monitor tool to validate the operation and configuration of HDX visualization technologies and to diagnose
and troubleshoot HDX issues. To download the tool and learn more about it, see https://taas.citrix.com/hdx/download/.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.483
GPU acceleration for Windows Desktop OS
Nov 28 , 20 17
With HDX 3D Pro you can deliver graphically intensive applications as part of hosted desktops or applications on Desktop
OS machines. HDX 3D Pro supports physical host computers (including desktop, blade, and rack workstations) and GPU
Passthrough and GPU virtualization technologies offered by XenServer, vSphere, and Hyper-V (passthrough only)
hypervisors.
Using GPU Passthrough, you can create VMs with exclusive access to dedicated graphics processing hardware. You can
install multiple GPUs on the hypervisor and assign VMs to each of these GPUs on a one-to-one basis.
Using GPU virtualization, multiple virtual machines can directly access the graphics processing power of a single physical GPU.
T he true hardware GPU sharing provides desktops suitable for users with complex and demanding design requirements. GPU
virtualization for NVIDIA GRID cards (see NVIDIA GRID) uses the same NVIDIA graphics drivers that are deployed on nonvirtualized operating systems. GPU virtualization is also supported for 5th and 6th Generation Intel CPUs with Intel Iris Pro
graphics with Intel GVT -g. For more information on these families of Intel processors, see 5th Generation Intel Core
Processors and 6th Generation Intel Core i5 Processors. GPU virtualization is also supported for AMD FirePro S-Series server
cards, see AMD Professional Graphics virtualization solution.
HDX 3D Pro offers the following features:
Adaptive H.264-based or H.265-based deep compression for optimal WAN and wireless performance. HDX 3D Pro uses
CPU-based full-screen H.264 compression as the default compression technique for encoding. Hardware encoding with
H.264 or H.265 is used with NVIDIA cards that support NVENC.
Lossless compression option for specialized use cases. HDX 3D Pro also offers a CPU-based lossless codec to support
applications where pixel-perfect graphics are required, such as medical imaging. T rue lossless compression is
recommended only for specialized use cases because it consumes significantly more network and processing resources.
When using lossless compression:
T he lossless indicator, a system tray icon, notifies the user if the screen displayed is a lossy frame or a lossless frame.
T his helps when the Visual Quality policy setting specifies Build to lossless. T he lossless indicator turns green when the
frames sent are lossless.
T he lossless switch enables the user to change to Always Lossless mode anytime within the session. T o select or
deselect Lossless anytime within a session, right-click the icon or use the shortcut ALT +SHIFT +1.
For lossless compression: HDX 3D Pro uses the lossless codec for compression regardless of the codec selected
through policy.
For lossy compression: HDX 3D Pro uses the original codec, either the default or the one selected through policy.
Lossless switch settings are not retained for subsequent sessions. To use lossless codec for every connection,
select Always lossless in the Visual quality policy setting.
You can override the default shortcut, ALT +SHIFT +1, to select or deselect Lossless within a session. Configure a new
registry setting at HKLM\SOFT WARE\Citrix\HDX3D\LLIndicator.
Name: HKLM_HotKey, T ype: String
T he format to configure a shortcut combination is C=0|1, A=0|1, S=0|1, W=0|1, K=val. Keys must be comma ","
separated. T he order of the keys does not matter.
A, C, S, W and K are keys, where C=Control, A=ALT , S=SHIFT , W=Win, and K=a valid key. Allowed values for K are 0-9,
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.484
a-z, and any virtual key code. For more information on virtual key codes, see Virtual-Key Codes on MSDN.
For example:
For F10, set K=0x79
For Ctrl + F10, set C=1, K=0x79
For Alt + A, set A=1, K=a or A=1, K=A or K=A, A=1
For Ctrl + Alt + 5, set C=1, A=1, K=5 or A=1, K=5, C=1
For Ctrl + Shift + F5, set A=1, S=1, K=0x74
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 Registry Editor can be solved. Use Registry Editor
at your own risk. Be sure to back up the registry before you edit it.
Multiple and high resolution monitor support. For desktop OS machines, HDX 3D Pro supports user devices with up to
four monitors. Users can arrange their monitors in any configuration and can mix monitors with different resolutions and
orientations. T he number of monitors is limited by the capabilities of the host computer GPU, the user device, and the
available bandwidth. HDX 3D Pro supports all monitor resolutions and is limited only by the capabilities of the GPU on the
host computer.
HDX 3D Pro also provides limited support for dual-monitor access to Windows XP desktops. For more information about
this, see VDAs on machines running Windows XP or Windows Vista.
Dynamic resolution. You can resize the virtual desktop or application window to any resolution. Note: T he only
supported method to change the resolution is by resizing the VDA session window. Changing resolution from within the
VDA session (using Control Panel > Appearance and Personalization > Display > Screen Resolution) is not supported.
Support for NVIDIA GRID architecture. HDX 3D Pro supports NVIDIA GRID cards (see NVIDIA GRID) for GPU
passthrough and GPU sharing. NVIDIA GRID vGPU enables multiple VMs to have simultaneous, direct access to a single
physical GPU, using the same NVIDIA graphics drivers that are deployed on non-virtualized operating systems.
Support for VMware vSphere and VMware ESX using Virtual Direct Graphics Acceleration (vDGA) - You can use HDX 3D
Pro with vDGA for both RDS and VDI workloads.
Support for VMware vSphere/ESX using NVIDIA GRID vGPU and AMD MxGPU.
Support for Microsoft HyperV using Discrete Device Assignment in Windows Server 2016.
Support for Data Center Graphics with Intel Xeon Processor E3 Family. HDX 3D Pro supports multi-monitors (up to 3),
console blanking, custom resolution, and high frame-rate with the supported family of Intel processors. For more
information, see http://www.citrix.com/intel and http://www.intel.com/content/www/us/en/servers/data-centergraphics.html.
Support for AMD RapidFire on the AMD FirePro S-series server cards. HDX 3D Pro supports multi-monitors (up to 6),
console blanking, custom resolution, and high frame-rate. Note: HDX 3D Pro support for AMD MxGPU (GPU
virtualization) works with VMWare vSphere vGPUs only. XenServer and Hyper-V are supported with GPU passthrough. For
more information, see AMD Virtualization Solution.
Access to a high-performance video encoder for NVIDIA GPUs and Intel Iris Pro graphics processors. T his feature is
controlled by a policy setting (enabled by default) and allows the use of hardware encoding for H.264 encoding (where
available). If such hardware is not available, the VDA will fall back to CPU-based encoding using the software video codec.
For more information, see Graphics policy settings.
As shown in the following figure:
When a user logs on to Citrix Receiver and accesses the virtual application or desktop, the Controller authenticates the
user and contacts the VDA for HDX 3D Pro to broker a connection to the computer hosting the graphical application.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.485
T he VDA for HDX 3D Pro uses the appropriate hardware on the host to compress views of the complete desktop or
of just the graphical application.
T he desktop or application views and the user interactions with them are transmitted between the host computer and
the user device through a direct HDX connection between Citrix Receiver and the VDA for HDX 3D Pro.
Install and upgrade NVIDIA drivers
T he NVIDIA GRID API provides direct access to the frame buffer of the GPU, providing the fastest possible frame rate for a
smooth and interactive user experience. If you install NVIDIA drivers before you install a VDA with HDX 3D Pro, NVIDIA
GRID is enabled by default.
To enable NVIDIA GRID on a VM, disable Microsoft Basic Display Adapter from the Device Manager. Run the following
command and then restart the VDA: NVFBCEnable.exe -enable -noreset
If you install NVIDIA drivers after you install a VDA with HDX 3D Pro, NVIDIA GRID is disabled. Enable NVIDIA GRID by using
the NVFBCEnable tool provided by NVIDIA.
To disable NVIDIA GRID, run the following command and then restart the VDA: NVFBCEnable.exe -disable -noreset
Install Intel graphics drivers
You can install the Intel graphics drivers before installing the VDA. T he following step is only required if you install Intel
drivers after you install a VDA with HDX 3D Pro or if the Intel driver has been updated.
In order to enable the Intel drivers required for multi-monitor support, run the following command using the
GfxDisplayTool.exe, then restart the VDA: Gf xDisplayTool.exe -vd enable
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.486
GfxDisplayTool.exe is included with the VDA installer. T he GfxDisplayTool.exe is in C:\Program Files\Citrix\ICAServices.
Note
Uninstalling NVIDIA or Intel drivers within ICA sessions is not supported.
Optimize the HDX 3D Pro user experience
To use HDX 3D Pro with multiple monitors, ensure that the host computer is configured with at least as many monitors as
are attached to user devices. T he monitors attached to the host computer can be either physical or virtual.
Do not attach a monitor (either physical or virtual) to a host computer while a user is connected to the virtual desktop or
application providing the graphical application. Doing so can cause instability for the duration of a user's session.
Let your users know that changes to the desktop resolution (by them or an application) are not supported while a graphical
application session is running. After closing the application session, a user can change the resolution of the Desktop Viewer
window in the Citrix Receiver - Desktop Viewer Preferences.
When multiple users share a connection with limited bandwidth (for example, at a branch office), Citrix recommends that
you use the Overall session bandwidth limit policy setting to limit the bandwidth available to each user. T his ensures that
the available bandwidth does not fluctuate widely as users log on and off. Because HDX 3D Pro automatically adjusts to
make use of all the available bandwidth, large variations in the available bandwidth over the course of user sessions can
negatively impact performance.
For example, if 20 users share a 60 Mbps connection, the bandwidth available to each user can vary between 3 Mbps and
60 Mbps, depending on the number of concurrent users. To optimize the user experience in this scenario, determine the
bandwidth required per user at peak periods and limit users to this amount at all times.
For users of a 3D mouse, Citrix recommends that you increase the priority of the Generic USB Redirection virtual channel to
0. For information about changing the virtual channel priority, see CT X128190.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.487
GPU acceleration for Windows Server OS
Nov 28 , 20 17
HDX 3D Pro allows graphics-heavy applications running in Windows Server OS sessions to render on the server's graphics
processing unit (GPU). By moving OpenGL, DirectX, Direct3D, and Windows Presentation Foundation (WPF) rendering to the
server's GPU, the server's CPU is not slowed by graphics rendering. Additionally, the server is able to process more graphics
because the workload is split between the CPU and GPU.
Since Windows Server is a multi-user operating system, a GPU accessed by XenApp can be shared by multiple users without
the need for GPU virtualization (vGPU).
For procedures that involve editing the registry, use 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 Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.
GPU sharing
GPU Sharing enables GPU hardware rendering of OpenGL and DirectX applications in remote desktop sessions; it has the
following characteristics:
Can be used on bare metal or virtual machines to increase application scalability and performance.
Enables multiple concurrent sessions to share GPU resources (most users do not require the rendering performance of a
dedicated GPU).
Requires no special settings.
You can install multiple GPUs on a hypervisor and assign VMs to each of these GPUs on a one-to-one basis: either install a
graphics card with more than one GPU, or install multiple graphics cards with one or more GPUs each. Mixing heterogeneous
graphics cards on a server is not recommended.
Virtual machines require direct passthrough access to a GPU, which is available with Citrix XenServer, VMware vSphere vDGA
and Intel GVT -d. When HDX 3D Pro is used with GPU Passthrough, each GPU in the server supports one multi-user virtual
machine.
GPU Sharing does not depend on any specific graphics card.
When running on a hypervisor, select a hardware platform and graphics cards that are compatible with your hypervisor's
GPU Passthrough implementation. T he list of hardware that has passed certification testing with XenServer GPU
Passthrough is available at GPU Passthrough Devices.
When running on bare metal, it is recommended to have a single display adapter enabled by the operating system. If
multiple GPUs are installed on the hardware, disable all but one of them using Device Manager.
Scalability using GPU Sharing depends on several factors:
T he applications being run
T he amount of video RAM they consume
T he graphics card's processing power
Some applications handle video RAM shortages better than others. If the hardware becomes extremely overloaded, this
could cause instability or a crash of the graphics card driver. Limit the number of concurrent users to avoid such issues.
To confirm that GPU acceleration is occurring, use a third-party tool such as GPU-Z. GPU-Z is available at
http://www.techpowerup.com/gpuz/.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.488
DirectX, Direct3D, and WPF rendering
DirectX, Direct3D, and WPF rendering is only available on servers with a GPU that supports a display driver interface (DDI)
version of 9ex, 10, or 11.
On Windows Server 2008 R2, DirectX and Direct3D require no special settings to use a single GPU.
On Windows Server 2016 and Windows Server 2012, Remote Desktop Services (RDS) sessions on the RD Session Host
server use the Microsoft Basic Render Driver as the default adapter. T o use the GPU in RDS sessions on Windows Server
2012, enable the Use the hardware default graphics adapter for all Remote Desktop Services sessions setting in the
group policy Local Computer Policy > Computer Configuration > Administrative T emplates > Windows Components >
Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment.
T o enable WPF applications to render using the server's GPU, create the following settings in the registry of the server
running Windows Server OS sessions:
[HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\CtxHook\AppInit_Dlls\Multiple Monitor Hook]
"EnableWPFHook"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFT WARE\Wow6432Node\Citrix\CtxHook\AppInit_Dlls\Multiple Monitor Hook]
"EnableWPFHook"=dword:00000001
GPU acceleration f or CUDA or OpenCL applications
GPU acceleration of CUDA and OpenCL applications running in a user session is disabled by default.
T o use the CUDA acceleration POC features, enable the following registry settings:
[HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\CtxHook\AppInit_Dlls\Graphics Helper] "CUDA"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFT WARE\Wow6432Node\Citrix\CtxHook\AppInit_Dlls\Graphics Helper]
"CUDA"=dword:00000001
T o use the OpenCL acceleration POC features, enable the following registry settings:
[HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\CtxHook\AppInit_Dlls\Graphics Helper] "OpenCL"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFT WARE\Wow6432Node\Citrix\CtxHook\AppInit_Dlls\Graphics Helper]
"OpenCL"=dword:00000001
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.489
OpenGL Software Accelerator
Nov 28 , 20 17
T he OpenGL Software Accelerator is a software rasterizer for OpenGL applications such as ArcGIS, Google Earth, Nehe,
Maya, Blender, Voxler, and CAD/CAM applications. Sometimes, the OpenGL Software Accelerator can eliminate the need to
use graphics cards to deliver a good user experience when using OpenGL applications.
Important
We provide the OpenGL Software Accelerator as is and must be tested using all applications because it might not support some
applications. If the Windows OpenGL rasterizer does not provide adequate performance, it is a solution to try . If the OpenGL
Software Accelerator supports your applications, you can use it as a way to avoid the cost of GPU hardware.
T he OpenGL Software Accelerator is provided in the support folder on the installation media, and is supported on all valid
VDA platforms.
When to try the OpenGL Software Accelerator:
On servers without graphics processing hardware, and the performance of OpenGL applications running in virtual
machines on XenServer or other hypervisors is an issue. For some applications, the OpenGL Accelerator outperforms the
Microsoft OpenGL software rasterizer that is included in Windows because the OpenGL Accelerator uses SSE4.1 and
AVX. OpenGL Accelerator also supports applications using OpenGL versions up to 2.1.
For applications running on a workstation, first try the default version of OpenGL support provided by the workstation
graphics adapter. If the graphics card is the latest version, usually it delivers the best performance. If the graphics card is
an earlier version or does not deliver satisfactory performance, try the OpenGL Software Accelerator.
3D OpenGL applications that are not adequately delivered using CPU-based software rasterization might benefit from
OpenGL GPU hardware acceleration. T his feature can be used on bare metal or virtual machines.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.490
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.491
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.492
Thinwire
Nov 28 , 20 17
Introduction
T hinwire is the Citrix default display remoting technology used in XenApp and XenDesktop.
Display remoting technology allows graphics generated on one machine to be transmitted, typically across a network, to
another machine for display.
A successful display remoting solution should provide a highly interactive user experience that is similar to that of a local PC.
T hinwire achieves this by using a range of complex and efficient image analysis and compression techniques. T hinwire
maximizes server scalability and consumes less bandwidth than other display remoting technologies.
Because of this balance, T hinwire meets most general business use cases and is used as the default display remoting
technology in XenApp and XenDesktop.
Thinwire or Framehawk
T hinwire should be used for delivering typical desktop workloads, for example, desktops, office productivity or browserbased applications. T hinwire is also recommended for multi-monitor, high resolution or high DPI scenarios, and for workloads
with a mixture of video and non-video content.
Framehawk should be used for mobile workers on broadband wireless connections where packet loss can be intermittently
high.
HDX 3D Pro
In its default configuration, T hinwire can deliver 3D or highly interactive graphics. However, we recommend enabling HDX 3D
Pro mode using the Citrix policy Optimize f or 3D graphics workload for such scenarios when GPUs are present. T he 3D
Pro mode uses the GPU for hardware acceleration and configures T hinwire using optimal settings for graphics. T his provides
a more fluid experience for 3D professional graphics. For more information, see HDX 3D Pro and GPU acceleration for
Windows Desktop OS.
Requirements and considerations
T hinwire has been optimized for modern operating systems, including Windows Server 2012 R2, Windows Server 2016,
Windows 7, and Windows 10. For Windows Server 2008 R2, legacy graphics mode is recommended. Use the built-in Citrix
policy templates, High Server Scalability-Legacy OS and Optimized for WAN-Legacy OS to deliver the Citrix
recommended combinations of policy settings for these use cases.
Note: We do not support legacy graphics mode in this release. It is included for backward compatibility when using
XenApp 7.15 LT SR, XenDesktop 7.15 LT SR, and previous VDA releases with Windows 7 and Windows 2008 R2.
T he policy setting which drives the behavior of T hinwire, Use video codec f or compression, is available on VDA versions
in XenApp and XenDesktop 7.6 FP3 and later. T he Use video codec when pref erred option is the default setting on
VDA versions XenApp and XenDesktop 7.9 and later.
All Citrix Receivers support T hinwire. Some Citrix Receivers may however support features of T hinwire that others do not,
for example, 8 or 16-bit graphics for reduced bandwidth usage. Support for such features are automatically negotiated
by Citrix Receiver.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.493
T hinwire will use more server resources (CPU, memory) in multi-monitor and high-resolution scenarios. It is possible to tune
the amount of resources T hinwire uses, however, bandwidth usage may increase as a result.
In low bandwidth or high latency scenarios, you may consider enabling 8 or 16-bit graphics to improve interactivity,
however visual quality will be affected, especially at 8-bit color depth.
Configuration
T hinwire is the default display remoting technology.
T he following Graphics policy setting sets the default and provides alternatives for different use cases:
Use video codec for compression
Use video codec when pref erred. T his is the default setting. No additional configuration is required. Keeping this
setting as the default ensures that T hinwire is selected for all Citrix connections, and is optimized for scalability,
bandwidth, and superior image quality for typical desktop workloads.
Other options in this policy setting will continue to use T hinwire in combination with other technologies for different use
cases. For example:
For actively changing regions. T he adaptive display technology in T hinwire identifies moving images (video, 3D in
motion) and uses H.264 or H.265 only in the part of the screen where the image is moving.
For the entire screen. Delivers T hinwire with full-screen H.264 or H.265 to optimize for improved user experience and
bandwidth, especially in cases with heavy use of 3D graphics.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.494
A number of other policy settings, including the following Visual display policy settings can be used to fine tune the
performance of display remoting technology and are all supported by T hinwire:
Preferred color depth for simple graphics
T arget frame rate
Visual quality
To get the Citrix recommended combinations of policy settings for different business use cases, use the built in Citrix Policy
templates. T he High Server Scalability and Very High Definition User Experience templates both use T hinwire with the
optimum combinations of policy settings for your organization's priorities and your users' expectations.
Monitoring Thinwire
You can monitor the use and performance of T hinwire from Citrix Director. T he HDX virtual channel details view contains
useful information for troubleshooting and monitoring T hinwire in any session. To view T hinwire-related metrics:
1. In Director, search for a user, machine or endpoint, open an active session and click Details. Or, you can select Filters >
Sessions > All Sessions, open an active session and click Details.
2. Scroll down to the HDX panel.
3. Select Graphics - Thinwire.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.495
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.496
Multimedia
Nov 28 , 20 17
T he HDX technology stack supports the delivery of multimedia applications through two complementary approaches:
Server-side rendering multimedia delivery
Client-side rendering multimedia redirection
T his strategy ensures that you can deliver a full range of multimedia formats, with a great user experience, while maximizing
server scalability to reduce cost-per-user.
With server-rendered multimedia delivery, audio and video content is decoded and rendered on the XenApp or XenDesktop
server by the application. T he content is then compressed and delivered over the ICA protocol to the Citrix Receiver on the
user device. T his method provides the highest rate of compatibility with various applications and media formats. Because
video processing is compute-intensive, server-rendered multimedia delivery benefits greatly from onboard hardware
acceleration. For example, support for DirectX Video Acceleration (DXVA) offloads the CPU by performing H.264 decoding
in separate hardware. Intel Quick Sync and NVIDIA NVENC technologies provided hardware-accelerated H.264 encoding.
Because most servers do not offer hardware acceleration for video compression, server scalability is negatively impacted if
all video processing is done on the server CPU. To maintain high server scalability, many multimedia formats can be redirected
to the user device for local rendering. Windows Media redirection offloads the server for a wide variety of media formats
typically associated with the Windows Media Player.
Flash redirection redirects Adobe Flash video content to a Flash player running locally on the user device.
HT ML5 video has become popular, and Citrix introduced a redirection technology for this type of content.
Also, you can apply the general contact redirection technologies Host-to-client redirection and Local App Access to
multimedia content.
Putting these technologies together, if you don't configure redirection, HDX does Server-Side Rendering.
If you configure redirection, HDX uses either Server Fetch and Client Render or Client Fetch and Client Render. If those
methods fail, HDX falls back to Server-Side Rendering as needed and is subject to the Fallback Prevention Policy.
Example scenarios
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.497
Scenario 1. (Server Fetch and Server Rendering)
1. T he server fetches the media file from its source, decodes, and then presents the content to an audio device or display
device.
2. T he server extracts the presented image or sound from the display device or audio device respectively.
3. T he server optionally compresses it, and then transmits it to the client.
T his approach incurs a high CPU cost, high bandwidth cost (if the extracted image/sound isn’t compressed efficiently), and
has low server scalability.
T hinwire and Audio virtual channels handle this approach. T he advantage of this approach is that it reduces the hardware
and software requirements for the clients. Using this approach the decoding happens on the server and it works for a wider
variety of devices and formats.
Scenario 2. (Server Fetch and Client Render)
T his approach relies on being able to intercept the media content before it is decoded and presented to the audio or
display device. T he compressed audio/video content is instead sent to the client where it is then decoded and presented
locally. T his advantage of this approach is that the decoding and presentation is offloaded to the client devices, saving CPU
cycles on the server.
However, it also introduces some additional hardware and software requirements for the client. T he client must be able to
decode each format that it might receive.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.498
Scenario 3. (Client Fetching and Client Rendering)
T his approach relies on being able to intercept the URL of the media content before it is fetched from the source. T he URL
is sent to the client where the media content is fetched, decoded, and presented locally. T his approach is conceptually
simple. Its advantage is that it saves both CPU cycles on the server and bandwidth because only control commands are sent
from the server. However, the media content is not always accessible to the clients.
Framework and platf orm
Desktop operating systems (Windows, Mac OS X, and Linux) provide multimedia frameworks that enable the faster and
easier development of multimedia applications. T his table lists some of the more popular multimedia frameworks. Each
framework divides media processing into several stages and uses a pipelined-based architecture.
Framework
Platf orm
DirectShow
Windows (98 and later)
Media Foundation
Windows (Vista and later)
Gstreamer
Linux
Quicktime
Mac OS X
Double hop support with media redirection technologies
HDX Flash redirection
No
Windows Media redirection
Yes
HT ML5 Video redirection
Yes
Audio redirection
N0
Related information
Audio features
Flash redirection
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.499
HT ML5 multimedia redirection
Windows Media redirection
General content redirection
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.500
Audio features
Nov 28 , 20 17
You can configure and add the following Citrix policy settings to a policy that optimizes HDX audio features. For usage
details plus relationships and dependencies with other policy settings, see Audio policy settings and Bandwidth policy
settings and Multi-stream connections policy settings.
Important
Although it is best to deliver audio using User Datagram Protocol (UDP) rather than TCP, UDP audio encryption using DT LS is
available only between NetScaler Gateway and Citrix Receiver. T herefore, sometimes it might be preferable to use TCP transport.
TCP supports end-to-end T LS encryption from the VDA to Citrix Receiver.
In general, higher sound quality consumes more bandwidth and server CPU utilization by sending more audio data to user
devices. Sound compression allows you to balance sound quality against overall session performance; use Citrix policy
settings to configure the compression levels to apply to sound files.
By default, the Audio quality policy setting is set to High - high definition audio when TCP transport is used, and to Medium
- optimized-for-speech when UDP transport (recommended) is used. T he High Definition audio setting provides high fidelity
stereo audio, but consumes more bandwidth than other quality settings. Do not use this audio quality for non-optimized
voice chat or video chat applications (such as softphones), because it may introduce latency into the audio path that is not
suitable for real-time communications. T he optimized for speech policy setting is recommended for real-time audio,
regardless of the selected transport protocol.
When bandwidth is limited, for example satellite or dial-up connections, reducing audio quality to Low consumes the least
possible bandwidth. In this situation, create separate policies for users on low-bandwidth connections so that users on
high-bandwidth connections are not adversely impacted.
For setting details, see Audio policy settings. Remember to enable Client audio settings on the user device; see Audio
setting policies for user devices.
To allow users to receive audio from an application on a server through speakers or other sound devices (such as
headphones) on the user device, leave the Client audio redirection setting at its default (Allowed).
Client audio mapping puts additional load on the servers and the network; however, prohibiting client audio redirection
disables all HDX audio functionality.
For setting details see Audio policy settings. Remember to enable client audio settings on the user device; see Audio setting
policies for user devices.
To allow users to record audio using input devices such as microphones on the user device leave the Client microphone
redirection setting at its default (Allowed).
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.501
For security, users are alerted when servers that are not trusted by their user devices try to access microphones, and can
choose to accept or reject access prior to using the microphone. Users can disable this alert on Citrix Receiver.
For setting details, see Audio policy settings. Remember to enable Client audio settings on the user device; see Audio
setting policies for user devices.
T he Audio Plug N Play policy setting allows or prevents the use of multiple audio devices to record and play sound. T his
setting is Enabled by default. Audio Plug N Play enables audio devices to be recognized even if they are not plugged in until
after the user session has been established.
T his setting applies only to Windows Server OS machines.
For setting details, see Audio policy settings.
T he Audio redirection bandwidth limit policy setting specifies the maximum bandwidth (in kilobits per second) for a playing
and recording audio in a session. T he Audio redirection bandwidth limit percent setting specifies the maximum bandwidth
for audio redirection as a percentage of the total available bandwidth. By default, zero (no maximum) is specified for both
settings. If both settings are configured, the one with the lowest bandwidth limit is used.
For setting details, see Bandwidth policy settings. Remember to enable Client audio settings on the user device; see Audio
setting policies for user devices.
By default, Audio over User Datagram Protocol (UDP) Real-time T ransport is allowed (when selected at time of installation),
opening up a UDP port on the server for connections that use Audio over UDP Real-time T ransport. Citrix recommends
configuring UDP/RT P for audio, to ensure the best possible user experience in the event of network congestion or packet
loss. For real time audio such as softphone applications, UDP audio is now preferred more than EDT . UDP allows for packet
loss without retransmission, ensuring that no latency is added on connections with high packet loss.
Import ant : Audio data transmitted with UDP is not encrypted when NetScaler Access Gateway is not in path. If NetScaler
Access Gateway is configured to access XenApp and XenDesktop resources then audio traffic between the endpoint
device and NetScaler Access Gateway is secured using DT LS protocol.
T he Audio UDP port range specifies the range of port numbers that the Virtual Delivery Agent (VDA) uses to exchange
audio packet data with the user device.
By default, the range is16500 - 16509.
For setting details about Audio over UDP Real-time Transport, see Audio policy settings; for details about Audio UDP port
range, see Multi-stream connections policy settings. Remember to enable Client audio settings on the user device; see
Audio setting policies for user devices.
1. Load the group policy templates by following Configure Receiver with the Group Policy Object template.
2. In the Group Policy Editor, expand Administrative T emplates > Citrix Components > Citrix Receiver > User Experience.
3. For Client audio set t ings , select Not Conf igured , Enabled , or Disabled .
Not Conf igured . By default Audio Redirection is enabled with high quality audio or previously configured custom
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.502
audio settings.
Enabled . Audio redirection is enabled with selected options.
Disabled . Audio redirection is disabled.
4. If you select Enabled , choose a sound quality. For UDP audio, use Medium (default).
5. For UDP audio only, select Enable Real-T ime T ransport and then set the range of incoming ports to open in the local
Windows firewall.
6. T o use UDP Audio with NetScaler Access Gateway, select Allow Real-T ime T ransport T hrough gat eway . NetScaler
Access Gateway should be configured with DT LS. For more information, see UDP Audio T hrough a Netscaler Gateway.
As an Administrator, if you do not have control on endpoint devices to make these changes, for example in the case of
BYOD or home computers, then use the default.ica attributes from StoreFront to enable UDP Audio.
1. On the StoreFront machine, open C:\inetpub\wwwroot\Citrix\<Store Name>\App_Data\default.ica with an editor such
as notepad.
2. Make the entries below under the [Application] section.
; This is to enable Real-Time Transport
EnableRtpAudio=true
; This is to Allow Real-Time Transport Through gateway
EnableUDPThroughGateway=true
; This is to set audio quality to Medium
AudioBandwidthLimit=1-
; UDP Port range
RtpAudioLowestPort=16500
RtpAudioHighestPort=16509
If you enable User Datagram Protocol (UDP) audio by editing default.ica, then UDP audio is enabled for all users who are
using that store.
Users in audio or video conferences might hear an echo. Echoes usually occur when speakers and microphones are too close
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.503
to each other. For that reason, we recommend the use of headsets for audio and video conferences.
HDX provides an echo cancellation option (enabled by default) that minimizes echo. T he effectiveness of echo cancellation
is sensitive to the distance between the speakers and the microphone. Devices should not be too close or too far away
from each other.
You can change a registry setting to disable echo cancellation.
Warning
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 Registry Editor can be solved. Use Registry Editor at your own risk. Be
sure to back up the registry before you edit it.
1. Using the Registry Editor on the user device, navigate to one of the following:
32-bit computers: HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\ICA
Client\Engine\Configuration\Advanced\Modules\ClientAudio\EchoCancellation
64-bit computers: HKEY_LOCAL_MACHINE\SOFT WARE\Wow6432Node\Citrix\ICA
Client\Engine\Configuration\Advanced\Modules\ClientAudio\EchoCancellation
2. Change the Value data field to FALSE.
A softphone is software acting as a phone interface. You use a softphone to make calls over the internet from a computer
or other smart device. By using a softphone, you can dial phone numbers and carry out other phone-related functions using
a screen.
XenApp and XenDesktop support several alternatives for delivering softphones.
Cont rol mode . T he hosted softphone simply controls a physical telephone set. In this mode, no audio traffic goes
through the XenApp or XenDesktop server.
HDX RealT ime opt imized sof t phone support . T he media engine runs on user device, and Voice over Internet
Protocol (VoIP) traffic flows peer-to-peer. For examples, see:
HDX RealT ime Optimization Pack, which optimizes the delivery of Microsoft Skype for Business and Lync.
Cisco Virtualization Experience Media Engine (VXME) for Jabber.
Avaya VDI Communicator for one-X Communicator and one-X Agent.
Local App Access . A XenApp and XenDesktop feature that allows an application such as a softphone to run locally on
the end user Windows device yet appear seamlessly integrated with their virtual/published desktop. T his offloads all
audio processing to the user device. For more information, see Local App Access and URL redirection.
HDX RealT ime generic sof t phone support . VoIP-over-ICA.
Generic sof t phone support
Generic softphone support, enables you to host an unmodified softphone on XenApp or XenDesktop in the data center.
T he audio traffic goes over the Citrix ICA protocol (preferably using UDP/RT P) to the user device running the Citrix Receiver.
Generic softphone support is a feature of HDX RealT ime. T his approach to softphone delivery is especially useful when:
An optimized solution for delivering the softphone is not available and the user is not on a Windows device where Local
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.504
App Access could be used.
T he media engine needed for optimized delivery of the softphone has not been installed on the user device or is not
available for the operating system version running on the user device. In this scenario, Generic HDX RealT ime provides a
valuable fallback solution.
T here are two softphone delivery considerations using XenApp and XenDesktop:
How the softphone application is delivered to the virtual/published desktop.
How the audio is delivered to and from the end user headset, microphone, and speakers, or USB telephone set.
XenApp and XenDesktop include numerous technologies to support generic softphone delivery:
Optimized-for-Speech codec for fast encode of real-time audio and bandwidth efficiency.
Low latency audio stack.
Server-side jitter buffer to smooth out the audio when network latency fluctuates.
Packet tagging (DSCP and WMM) for Quality of Service.
DSCP tagging for RT P packets (Layer 3)
WMM tagging for Wi-Fi
T he Citrix Receiver versions for Windows, Linux, Chrome, and Mac also are VoIP capable. Citrix Receiver for Windows offers
these features:
Client-side jitter buffer - Ensures smooth audio even when network latency fluctuates.
Echo cancellation - Allows for greater variation in the distance between microphone and speakers for workers who do
not use a headset.
Audio plug-n-play - Audio devices do not need to be plugged in before starting a session. T hey can be plugged in at any
time.
Audio device routing - Users can direct ringtone to speakers but the voice path to their headset.
Multi-stream ICA - Enables flexible Quality of Service (QoS)-based routing over the network.
ICA supports four T CP and two UDP streams. One of the UDP streams supports real-time audio over RT P.
For a summary of Citrix Receiver capabilities, see Citrix Receiver Feature Matrix.
Syst em configurat ion recommendat ions
Client Hardware and Software:
For optimal audio quality, we recommend the latest version of Citrix Receiver and a good quality headset with acoustic
echo cancellation (AEC). Citrix Receiver versions for Windows, Linux, and Mac support VoIP. Also, Dell Wyse offers VoIP
support for T hinOS (WTOS).
CPU Considerations:
Monitor CPU usage on the VDA to determine if it is necessary to assign two virtual CPUs to each virtual machine. Real-time
voice and video are data intensive. Configuring two virtual CPUs reduces the thread switching latency. T herefore, we
recommend that you configure two vCPUs in a XenDesktop VDI environment.
Having two virtual CPUs does not necessarily mean doubling the number of physical CPUs, because physical CPUs can be
shared across sessions.
Citrix Gateway Protocol (CGP), which is used for the Session Reliability feature, also increases CPU consumption. On highquality network connections, you can disable this feature to reduce CPU consumption on the VDA. Neither of the
preceding steps might be necessary on a powerful server.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.505
UDP Audio:
Audio over UDP provides excellent tolerance of network congestion and packet loss. We recommend it instead of TCP
when available.
LAN/WAN configuration:
Proper configuration of the network is critical for good real-time audio quality. Typically, you must configure virtual LANs
(VLANs) because excessive broadcast packets can introduce jitter. IPv6-enabled devices might generate a lot of broadcast
packets. If IPv6 support is not needed, you can disable IPv6 on those devices. Configure to support Quality of Service.
Settings for use WAN connections:
You can use voice chat over Local Area Network (LAN) and Wide Area Network (WAN) connections. On a WAN connection,
audio quality depends on the latency, packet loss, and jitter on the connection. If delivering softphones to users on a WAN
connection, we recommend using the NetScaler SD-WAN between the data center and the remote office to maintain a
high Quality-of-Service. NetScaler SD-WAN supports Multi-Stream ICA, including UDP. Also, in the case of a single TCP
stream, it is possible to distinguish the priorities of various ICA virtual channels to ensure that high priority real-time audio
data gets preferential treatment.
Use Director or the HDX Monitor to validate your HDX configuration.
Remote user connections:
NetScaler Gateway 11 supports DT LS to deliver UDP/RT P traffic natively (without encapsulation in TCP).
You must open firewalls bidirectionally for UDP traffic over Port 443.
Codec selection and bandwidth consumption:
Between the user device and the Virtual Delivery Agent (VDA) in the data center, we recommend using the Optimized-forSpeech codec setting, also known as Medium Quality audio. Between the VDA platform and the IP-PBX, the softphone
uses whatever codec is configured or negotiated. For example:
G711 provides very good voice quality but has a bandwidth requirement of 80 to 100 kilobits per second per call
(depending on Network Layer2 overheads).
G729 provides good voice quality and has a low bandwidth requirement of 30 to 40 kilobits per second per call
(depending on Network Layer 2 overheads).
Delivering sof t phone applicat ions t o t he virt ual deskt op
T here are two methods by which you can deliver a softphone to the XenDesktop virtual desktop:
T he application can be installed in the virtual desktop image.
T he application can be streamed to the virtual desktop using Microsoft App‑V. T his approach has manageability
advantages because the virtual desktop image is kept uncluttered. After being streamed to the virtual desktop, the
application executes in that environment as if it had been installed in the usual manner. Not all applications are
compatible with App-V.
Delivering audio t o and f rom t he user device
Generic HDX RealT ime supports two methods of delivering audio to and from the user device:
Cit rix Audio Virt ual Channel. We generally recommend the Citrix Audio Virtual Channel because it's designed
specifically for audio transport.
Generic USB Redirect ion . Useful to support audio devices having buttons and/or a display, human interface device
(HID), if the user device is on a LAN or LAN-like connection back to the XenApp or XenDesktop server.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.506
Cit rix audio virt ual channel
T he bidirectional Citrix Audio Virtual Channel (CT XCAM) enables audio to be delivered efficiently over the network. Generic
HDX RealT ime takes the audio from the user headset or microphone, compresses it, and sends it over ICA to the softphone
application on the virtual desktop. Likewise, the audio output of the softphone is compressed and sent in the other
direction to the user headset or speakers. T his compression is independent of the compression used by the softphone itself
(such as G.729 or G.711). It is done using the Optimized-for-Speech codec (Medium Quality). Its characteristics are ideal for
voice-over-IP (VoIP). It features quick encode time, and it consumes only approximately 56 Kilobits per second of network
bandwidth (28 Kbps in each direction), peak. T his codec must be explicitly selected in the Studio console because it is not
the default audio codec. T he default is the HD Audio codec (High Quality). T his codec is excellent for high fidelity
stereophonic soundtracks but is slower to encode compared to the Optimized-for-Speech codec.
Generic USB Redirect ion
Citrix Generic USB Redirection technology (CT XGUSB virtual channel) provides a generic means of remoting USB devices,
including composite devices (audio plus HID) and isochronous USB devices. T his approach is limited to LAN-connected users
because the USB protocol tends to be sensitive to network latency and requires considerable network bandwidth.
Isochronous USB redirection works well when using some softphones. T his redirection provides excellent voice quality and
low latency, but Citrix Audio Virtual Channel is preferred because it is optimized for audio traffic. T he primary exception is
when using an audio device with buttons such as a USB telephone attached to the user device that is LAN-connected to
the data center. In this case, Generic USB Redirection supports buttons on the phone set or headset that control features
by sending a signal back to the softphone. T his isn't an issue with buttons that work locally on the device.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.507
Browser content redirection
Jan 16, 20 18
Browser content redirection prevents the rendering of whitelisted webpages on the VDA side. T his feature uses Citrix
Receiver to instantiate a corresponding rendering engine on the client side, which fetches the HT T P and HT T PS content
from the URL.
T his overlay web layout engine runs on the endpoint device instead of on the VDA and uses the endpoint CPU and RAM.
Only the browser viewport is redirected. T he viewport is the rectangular area in your browser where content displays. T he
viewport doesn't include things like the Address Bar, Favorites Toolbar, Status Bar. T hose items are in the user interface.
1. Configure a Studio policy that specifies and Access Control List containing the URLs whitelisted for redirection. For the
browser on the VDA to detect that the URL, which the user is navigating to matches the whitelist, a browser extension
performs the comparison. T he browser extension is included with the installation media and is installed automatically.
2. If a match is found, a virtual channel (CT XCSB) instructs Citrix Receiver that a redirection is required and relays the URL.
Citrix Receiver then instantiates a local rendering engine (already present natively in the client operating system) and
displays the website.
3. Citrix Receiver then blends back the website into the virtual desktop browser content area seamlessly.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.508
T here are three scenarios of how Citrix Receiver fetches content:
Server f et ch and server render: T here is no redirection because you didn't whitelist the site or the redirection failed.
We fall back to rendering the webpage on the VDA and use T hinwire to remote the graphics. Use policies to control the
fallback behavior. High CPU, RAM, and bandwidth consumption on the VDA.
Server f et ch and client render: Citrix Receiver contacts and fetches content from the web server through the VDA
using a virtual channel (CT XPFWD). T his option is useful when the client doesn't have internet access (for example, thin
clients). Low CPU and RAM consumption on the VDA, but bandwidth is consumed on the ICA virtual channel.
Client f et ch and client render: Because Citrix Receiver contacts the web server directly, it requires internet access.
T his scenario offloads all the network, CPU, and RAM usage from your XenApp and XenDesktop Site.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.509
Fallback mechanism
T here might be times when client redirection fails. For example, if the client machine does not have direct internet access,
an error response might go back to the VDA. In such cases, the Internet Explorer browser on the VDA can then reload and
render the page on the server.
Syst em Requirement s:
Client operating system:
Windows 7, 8.x, or 10 and Internet Explorer 11.
Citrix Receiver for Windows minimum version 4.10
XenApp / XenDesktop 7.16:
VDA operating system: Windows 10 (minimum version 1607), Windows Server 2012 R2, Windows Server 2016
Browser on the VDA: Internet Explorer 11 and configure these options:
Deselct Enhanced P rot ect ed Mode under: Int ernet Opt ions > Advanced > Securit y
Check Enable t hird-part y browser ext ensions under: Int ernet Opt ions > Advanced > Browsing
Client side opt imizat ion
HdxBrowser.exe is the overlay browser on the endpoint that is responsible for client-side rendering. To enable
HdxBrowser.exe to use the GPU resources on the client, set these registry keys on the Windows endpoint.
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
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.510
sure to back up the registry before you edit it.
\HKEY_LOCAL_MACHINE \SOFT WARE\Microsoft\Internet Explorer\Main\FeatureControl\FEAT URE_GPU_RENDERING
(create if not present)
and
\HKEY_CURRENT _USER) \SOFT WARE\Microsoft\Internet Explorer\Main\FeatureControl\FEAT URE_GPU_RENDERING
(create if not present)
Value name: HdxBrowser.exe
Value data: 00000001
Type: DWORD
Related information
Browser content redirection policy settings
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.511
Flash redirection
Nov 28 , 20 17
Important
On July 25, 2017, Adobe announced End of Life (EOL) for Flash. Adobe plans to stop updating and distributing the Flash Player at the
end of 2020.
Microsoft announced that they are phasing out Flash support in Internet Explorer before the Adobe date. T hey are removing Flash
from Windows by the end of 2020. When that happens, users can no longer enable or run Flash in Internet Explorer.
Citrix aligns with Microsoft policy and continues to maintain and support HDX Flash Redirection until the end of 2020. We haven't
decided in which versions of XenApp and XenDesktop to exclude the Flash Redirection code, but we recommend that you switch to
HT ML5 Video Redirection whenever possible. HT ML5 Video Redirection is ideal to control the multimedia content. For example,
corporate communications videos, training videos, or when a third party hosts the content.
For more information about HT ML5 Video Redirection, see HT ML5 multimedia redirection.
Flash Redirection offloads the processing of most Adobe Flash content (including animations, videos, and applications) to
users' LAN- and WAN-connected Windows and 32-bit Linux x86 devices, which reduces server and network load. T his results
in greater scalability while ensuring a high definition user experience. Configuring Flash Redirection requires both server-side
and client-side settings.
Caut ion: Flash Redirection involves significant interaction between the user device and server components. Use this feature
only in environments where security separation between the user device and server is not required. Additionally, configure
user devices to use this feature only with trusted servers. Because Flash Redirection requires the Adobe Flash Player to be
installed on the user device, enable this feature only if the Flash Player itself is secured.
Flash Redirection is supported on both clients and servers. If the client supports second generation Flash Redirection, Flash
content renders on the client. Flash Redirection features include support for user connections over WAN, intelligent fallback,
and a URL compatibility list; see below for details.
Flash Redirection uses Windows event logging on the server to log Flash events. T he event log indicates whether Flash
Redirection is being used and provides details about issues. T he following are common to all events logged by Flash
Redirection:
Flash Redirection reports events to the Application log.
On Windows 10, Windows 8 and Windows 7 systems, a Flash Redirection-specific log appears in the Applications and
Services Logs node.
T he Source value is Flash.
T he Category value is None.
For the latest updates to HDX Flash compatibility, see CT X136588.
T o configure Flash Redirection on the server, use the following Citrix policy settings. For details, see Flash Redirection policy
settings.
By default, Flash Redirection is enabled. T o override this default behavior for individual web pages and Flash instances, use
the Flash URL compatibility list setting.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.512
Flash intelligent fallback - detects instances of small Flash "movies" (such as those frequently used to play
advertisements) and renders them on the server instead of redirecting them for rendering on the user device. T his
optimization does not cause any interruption or failure in the loading of the web page or the Flash application. By
default, Flash intelligent fallback is enabled. T o redirect all instances of Flash content for rendering on the user device,
disable this policy setting. Note that some Flash content may not be successfully redirected.
Flash server-side content fetching URL list allows you to specify websites whose Flash content should be downloaded to
the server and then transferred to the user device for rendering. (By default, Flash Redirection downloads Flash content
directly to the user device with client-side fetching.) T his setting works with (and requires) the Enable server-side content
fetching setting on the user device and is intended primarily for use with Intranet sites and internal Flash applications; see
below for details. It also works with most Internet sites and can be used when the user device does not have direct
access to the Internet (for example, when the XenApp or XenDesktop server provides that connection).
Note: Server-side content fetching does not support Flash applications using Real T ime Messaging Protocols (RT MP);
instead, server-side rendering is used, which supports HT T P and HT T PS.
Flash URL compatibility list - specifies where Flash content from listed websites is rendered: on the user device, on the
server, or blocked.
Flash background color list - enables you to match the colors of web pages and Flash instances, which improves the
appearance of the web page when using Flash Redirection.
Install Citrix Receiver and Adobe Flash Player on the user device. No further configuration is required on the user device.
You can change the default settings using Active Directory Group Policy Objects. Import and add the HDX MediaStream
Flash Redirection - Client administrative template (HdxFlashClient.adm), which is available in the following folders:
For 32-bit computers: %Program Files%\Citrix\ICA Client\Configuration\language
For 64-bit computers: %Program Files (x86)%\Citrix\ICA Client\Configuration\language
T he policy settings appear under Administrative Templates > Classic Administrative Templates (ADM) > HDX MediaStream
Flash Redirection - Client. See the Microsoft Active Directory documentation for details about GPOs and templates.
Change when F lash Redirect ion is used
Together with server-side settings, the Enable HDX MediaStream Flash Redirection on the user device policy setting controls
whether Adobe Flash content is redirected to the user device for local rendering. By default, Flash Redirection is enabled and
uses intelligent network detection to determine when to play Flash content on the user device.
If no configuration is set and Desktop Lock is used, Flash Redirection is enabled on the user device by default.
T o change when Flash Redirection is used or to disable Flash Redirection on the user device:
1. From the Setting list, select Enable HDX MediaStream Flash Redirection on the user device and click policy setting.
2. Select Not Configured, Enabled (the default), or Disabled.
3. If you select Enabled, choose an option from the Use HDX MediaStream Flash Redirection list:
T o use the latest Flash Redirection functionality when the required configuration is present, and revert to server-side
rendering when it is not, select Only with Second Generation.
T o always use Flash Redirection, select Always. Flash content plays on the user device.
T o never use Flash Redirection, select Never. Flash content plays on the server.
T o use intelligent network detection to assess the security level of the client-side network to determine when using
Flash Redirection is appropriate, select Ask (the default). If the security of the network cannot be determined, the user
is asked whether to use Flash Redirection. If the network security level cannot be determined, the user is prompted to
choose whether to use Flash Redirection.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.513
T he following illustration indicates how Flash Redirection is handled for various network types.
Users can override intelligent network detection from the Citrix Receiver - Desktop Viewer Preferences dialog box by
selecting Optimize or Don't Optimize in the Flash tab. T he choices available vary depending on how Flash Redirection is
configured on the user device, as shown in the following illustration.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.514
Synchronize client -side HT T P cookies wit h t he server-side
Synchronization of the client-side HT T P cookies with the server-side is disabled by default. Enable synchronization to
download HT T P cookies from the server; those HT T P cookies are then used for client-side content fetching and are
available as needed by sites containing Flash content.
Note: Client-side cookies are not replaced during the synchronization; they remain available even if the synchronization
policy is later disabled.
1. From the Setting list, select Enable synchronization of the client-side HT T P cookies with the server-side and click policy
setting.
2. Select Not Configured, Enabled, or Disabled (the default).
Enable server-side cont ent f et ching
By default, Flash Redirection downloads Adobe Flash content directly to the user device, where it is played. Enabling serverside content fetching causes the Flash content to download to the server and then be sent to the user device. Unless there
is an overriding policy (such as a site blocked with the Flash URL compatibility list policy setting), the Flash content plays on
the user device.
Server-side content fetching is frequently used when the user device connects to internal sites through NetScaler Gateway
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.515
and when the user device does not have direct access to the Internet.
Note: Server-side content fetching does not support Flash applications using Real T ime Messaging Protocols (RT MP).
Instead, server-side rendering is used for such sites.
Flash Redirection supports three enabling options for server-side content fetching. Two of these options include the ability
to cache server-side content on the user device, which improves performance because content that is reused is already
available on the user device for rendering. T he contents of this cache are stored separately from other HT T P content
cached on the user device.
Fallback to server-side content fetching begins automatically when any of the enabling options is selected and client-side
fetching of .swf files fails.
Enabling server-side content fetching requires settings on both the client device and the server.
1. From the Setting list, select Enable server-side content fetching and click policy setting.
2. Select Not Configured, Enabled, or Disabled (the default). If you enable this setting, choose an option from the Serverside content fetching state list:
Opt ion
Descript ion
Disabled
Disables server-side content fetching, overriding the Flash server-side content fetching URL list setting
on the server. Server-side content fetching fallback is also disabled.
Enabled
Enables server-side content fetching for web pages and Flash applications identified in the Flash serverside content fetching URL list. Server-side content fetching fallback is available, but Flash content is not
cached.
Enabled
Enables server-side content fetching for web pages and Flash applications identified in the Flash server-
(persistent
side content fetching URL list. Server-side content fetching fallback is available. Content obtained
caching)
through server-side fetching is cached on the user device and stored from session to session.
Enabled
Enables server-side content fetching for web pages and Flash applications identified in the Flash server-
(temporary
side content fetching URL list. Server-side content fetching fallback is available. Content obtained
caching)
through server-side fetching is cached on the user device and deleted at the end of the session.
3. On the server, enable the Flash server-side content fetching URL list policy setting and populate it with target URLs.
Redirect user devices t o ot her servers f or client -side cont ent f et ching
To redirect an attempt to obtain Flash content, use the URL rewriting rules for client-side content fetching setting, which is
a second generation Flash Redirection feature. When configuring this feature, you provide two URL patterns; when the user
device attempts to fetch content from a website matching the first pattern (the URL match pattern), it is redirected to the
website specified by the second pattern (the rewritten URL format).
You can use this setting to compensate for content delivery networks (CDN). Some websites delivering Flash content use
CDN redirection to enable the user to obtain the content from the nearest of a group of servers containing the same
content. When using Flash Redirection client-side content fetching, the Flash content is requested from the user device,
while the rest of the web page on which the Flash content resides is requested by the server. If CDN is in use, the server
request is redirected to the nearest server, and the user device request follows to the same location. T his may not be the
location closest to the user device; depending on distance, there could be a noticeable delay between the loading of the
web page and the playing of the Flash content.
1. From the Setting list, select URL rewriting rules for client-side content fetching and click policy setting.
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.516
2. Select Not Configured, Enabled, or Disabled. Not Configured is the default; Disabled causes any URL rewriting rules
specified in the next step to be ignored.
3. If you enable the setting, click Show. Using Perl regular expression syntax, type the URL match pattern in the Value name
box and the rewritten URL format in the Value box.
Warning
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 Registry Editor can be solved. Use Registry Editor at your own risk. Be
sure to back up the registry before you edit it.
You can add registry settings to specify the minimum version required for Flash redirection for client devices accessing VDAs
using Citrix Receiver for Windows or Citrix Receiver for Linux. T his security feature ensures that an outdated Flash version is
not used.
ServerF lashP layerVersionMinimum is a string value that specifies the minimum version of the Flash Player required on the
ICA Server (VDA).
Client F lashP layerVersionMinimum is a string value that specifies the minimum version of the Flash Player required on the
ICA Client (Citrix Receiver).
T hese version strings can be specified as "10" or "10.2" or "10.2.140". Only the major, minor and build numbers will be
compared. T he revision number will be ignored. For example, for a version string specified as "10" with only the major number
specified, the minor and build numbers will be assumed to be zero.
F lashP layerVersionComparisonMask is a DWORD value that when set to zero will disable comparing the version of the
Flash Player on the ICA Client against the Flash Player on the ICA Server. T he comparison mask has other values, but these
should not be used because the meaning of any non-zero mask may change. It is recommended to only set the comparison
mask to zero for the desired clients. It is not recommended to set the comparison mask under the client agnostic settings. If
a comparison mask is not specified, Flash redirection will require that the ICA Client has a Flash Player with greater or equal
version to the Flash Player on the ICA Server. It will do so by comparing only the major version number of the Flash Player.
In order for redirection to occur the client and server minimum checks need to be successful in addition to the check using
the comparison mask.
T he subkey ClientID0x51 specifies Citrix Receiver for Linux. T he subkey ClientID0x1 specifies Citrix Receiver for Windows. T his
subkey is named by appending the hexadecimal Client Product ID (without any leading zeros) to the string "ClientID".
32-bit VDA example regist ry configurat ion
[HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\HdxMediaStreamForFlash\Server\PseudoServer] Client agnostic settings
"ClientFlashPlayerVersionMinimum"="13.0" Minimum version required for the ICA client
"ServerFlashPlayerVersionMinimum"="13.0" Minimum version required for the ICA server
[HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\HdxMediaStreamForFlash\Server\PseudoServer\ClientID0x1] Windows ICA
Client settings
https://docs.citrix.com
© 1999-2017 Citrix Systems, Inc. All rights reserved.
p.517
"ClientFlashPlayerVersionMinimum"="16.0.0" T his specifies the minimum version of the Flash Player required for the Windows
client [HKEY_LOCAL_MACHINE\SOFT WARE\Citrix\HdxMed