Linux Virtual Delivery Agent

1912 LTSR

Citrix Product Documentation | https://docs.citrix.com February 23, 2024

Linux Virtual Delivery Agent 1912 LTSR

Contents

What’s new 4

Cumulative Update 8 (CU8) 4

Cumulative Update 7 (CU7) 5

Fixed issues in 1912 LTSR CU7 Hotfix 1 (19.12.7001) 5

Cumulative Update 6 (CU6) 6

Cumulative Update 5 (CU5) 6

Fixed issues in 1912 LTSR CU5 7

Cumulative Update 4 (CU4) 7

Fixed issues in 1912 LTSR CU4 8

Cumulative Update 3 (CU3) 8

Fixed issues in 1912 LTSR CU3 9

Cumulative Update 2 (CU2) 9

Fixed issues in 1912 LTSR CU2 10

Cumulative Update 1 (CU1) 11

Fixed issues in 1912 LTSR CU1 11

About this release 12

Fixed issues in 1912 LTSR 13

Known issues 13

Third party notices 15

Deprecation 15

System requirements 16

Installation overview 20

Quick installation by using easy install (Recommended) 21

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 1

Linux Virtual Delivery Agent 1912 LTSR

Install Linux Virtual Delivery Agent for RHEL/CentOS manually 38

Install Linux Virtual Delivery Agent for SUSE manually 70

Install Linux Virtual Delivery Agent for Ubuntu manually 93

Use Machine Creation Services (MCS) to create Linux VMs 123

Configure the Linux VDA 151

Integrate NIS with Active Directory 152

Publish applications 157

Remote PC Access 159

Print 169

File transfer 176

PDF printing 180

Configure graphics 181

Thinwire progressive display 189

Non‑GRID 3D graphics 192

Configure policies 194

Policy support list 196

Configure IPv6 204

Configure Citrix Customer Experience Improvement Program (CEIP) 205

Configure USB redirection 209

Configure session reliability 219

Soft keyboard 221

Client Input Method Editor (IME) 224

Support for multiple language inputs 225

Dynamic keyboard layout synchronization 226

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 2

Linux Virtual Delivery Agent 1912 LTSR

Client IME user interface synchronization 228

HDX Insight 230

Adaptive transport 231

Tracing On 233

Shadow sessions 236

Support Citrix Workspace app for HTML5 242

Monitor Linux sessions in Citrix Director 243

Monitor service daemon 243

Secure user sessions using TLS 246

Secure user sessions using DTLS 250

Support for smart cards 251

Double‑hop single sign‑on authentication 262

Configure unauthenticated sessions 265

Configure LDAPS 267

Configure Xauthority 271

Federated Authentication Service 273

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 3

Linux Virtual Delivery Agent 1912 LTSR

What’s new

September 12, 2023

Cumulative Update 8 (CU8) is the latest release of the Linux Virtual Delivery Agent 1912 LTSR. CU8
addresses several issues that help to improve overall performance, security, and stability.

Note:

Starting with the CU3 release, install .NET Core Runtime 3.1 as a prerequisite before you install
the Linux VDA.

Cumulative Update 8 (CU8)

September 12, 2023

Release date: September 11, 2023

About this release

Cumulative Update 8 (CU8) is the latest release of the Linux Virtual Delivery Agent 1912 LTSR. CU8
addresses several issues that help to improve overall performance, security, and stability.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 7 (CU7) Hotfix 1 (19.12.7001)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 7 (CU7)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 6 (CU6)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 5 (CU5)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 4 (CU4)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 4

Linux Virtual Delivery Agent 1912 LTSR

Cumulative Update 7 (CU7)

June 13, 2023

Release date: March 15, 2023

About this release

Cumulative Update 7 (CU7) Hotfix 1 (19.12.7001) is the latest release of the Linux Virtual Delivery Agent
1912 LTSR. This hotfix fixes one issue reported since the release of the 1912 LTSR CU7.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 7 (CU7)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 6 (CU6)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 5 (CU5)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 4 (CU4)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU7 Hotfix 1 (19.12.7001)

June 13, 2023

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU7:

• This fix addresses a security issue. For more information, see Knowledge Center article
CTX559370.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 5

Linux Virtual Delivery Agent 1912 LTSR

Fixed issues in 1912 LTSR CU7

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU6:

• When you connect to a Linux VDA session from a laptop running Microsoft Windows and the
close lid action of the laptop is set to Do nothing, Hibernate, or Sleep, random keys might be
injected into the VDA session. [CVADHELP‑18438]

• When you connect certain laptops to a Linux VDA and press the Fn key, it might function as a
Delete key. [CVADHELP‑21630]

Cumulative Update 6 (CU6)

October 31, 2022

Release date: October 31, 2022

About this release

CU6 contains no fixed issues.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 5 (CU5)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 4 (CU4)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Cumulative Update 5 (CU5)

March 9, 2022

Release date: March 09, 2022

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 6

Linux Virtual Delivery Agent 1912 LTSR

About this release

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 5 (CU5) fixes two issues reported since the
release of the 1912 LTSR CU4.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 4 (CU4)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU5

March 8, 2022

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU4:

• A Linux VDA desktop might not respond to keyboard and mouse inputs. [CVADHELP‑18498]

• Shutting down one domain controller in an environment with multiple domain controllers
might cause session launches on Linux VDA to fail. [CVADHELP‑18900]

Cumulative Update 4 (CU4)

December 21, 2021

Release date: November 03, 2021

About this release

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 4 (CU4) fixes three issues reported since
the release of the 1912 LTSR CU3.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3)

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 7

Linux Virtual Delivery Agent 1912 LTSR

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU4

December 21, 2021

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU3:

• On a Linux VDA connected using Citrix Workspace app for Mac or Linux, pressing Shift + Tab
might be registered as a double press of the Shift key. [CVADHELP‑16831]

• Attempting to launch Linux VDA sessions on RHEL might fail if Machine Creation Services are
used to create Linux VMs in Azure. [CVADHELP‑17244]

• Uninstalling Linux VDAs on SUSE or RHEL might not delete empty folders in the /opt/Citrix/ lo‑
cation. [CVADHELP‑18241]

Cumulative Update 3 (CU3)

December 21, 2021

Release date: May 12, 2021

About this release

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 3 (CU3) fixes nine issues reported since the
release of the 1912 LTSR CU2.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2)

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 8

Linux Virtual Delivery Agent 1912 LTSR

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU3

December 21, 2021

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU2:

• After upgrading a 64‑bit Linux VDA, user attempts to start applications can fail. Users see a mes‑
sage indicating that the application is starting, then the message disappears. As a result, multi‑
ple stale sessions remain on the VDA. [CVADHELP‑15899]

• After performing scans, the ctxmonitorservice process might exit unexpectedly with a
SIGABRT error. [CVADHELP‑15969]

• Attempts to select the Picture Transfer Protocol (PTP) and Media Transfer Protocol (MTP) USB
options, might fail on a Xiaomi Mi 10 phone. [CVADHELP‑16188]

• When the Citrix Desktop Viewer (CDViewer.exe) window disappears, attempts to reconnect to
the Linux VDA might fail. [CVADHELP‑16239]

• In Linux VDAs, some applications might not recognize a webcam device that appears in the De‑
vice option. [CVADHELP‑16247]

• When using USB redirection for a webcam in a Linux VDA session, the ctxusbsd process might
exit unexpectedly with a segfault error. [CVADHELP‑16366]

• The ctxcdmd process might not run in the correct SELinux security context. [CVADHELP‑16381]

• A smart card might fail to work when it is configured to a Linux VDA. [CVADHELP‑16488]

• The text appearing in a Linux VDA session might be distorted and blurry. [CVADHELP‑17199]

Cumulative Update 2 (CU2)

December 21, 2021

Release date: November 19, 2020

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 9

Linux Virtual Delivery Agent 1912 LTSR

About this release

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 2 (CU2) fixes five issues reported since the
release of the 1912 LTSR CU1.

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1)

Linux Virtual Delivery Agent 1912 LTSR (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU2

December 21, 2021

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR CU1:

• With LDAP signing enabled, attempts to register a Linux VDA with the Delivery Controller might
fail. [CVADHELP‑14481]

• Attempts to launch a VDA might result in a gray screen. The issue is the result of a timeout of
the HDX user policy validation. The timeout can occur when there are many LDAP servers and
one or more servers are not accessible to the VDA. [CVADHELP‑14746]

• The Linux VDA might recognize only Client USB device redirection rules, the topmost rule in
the HDX policy setting. The other rules are discarded. [CVADHELP‑14971]

• When you launch a published application in seamless mode, the published application is always
on top, appearing over local applications. You can bring the local applications to the foreground
only when you minimize the published application. [CVADHELP‑15134]

• When you log on to a Ubuntu virtual machine created by the Machine Creation Services (MCS),
certain files such as .bashrc and .profile might not be copied automatically to the home folder
as expected. [CVADHELP‑15306]

• With a NVIDIA GRID graphics card installed on a Linux VDA running Ubuntu, the session might
exit unexpectedly when you attempt to resize the session. [CVADHELP‑15664]

• Changing the locale to a non‑English language might make performance counters unable to
convert a string value to a numeric value and generate the following error in the VDA log.

[PerfCounter] [Error] SysStat.ReadUpTime: Converting element ‘29363.68’resulted in a

NumberFormatException. Error: Input string was not in a correct format.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 10

Linux Virtual Delivery Agent 1912 LTSR

[CVADHELP‑15767]

Cumulative Update 1 (CU1)

May 12, 2020

Release date: May 7, 2020

About this release

Linux Virtual Delivery Agent 1912 LTSR Cumulative Update 1 (CU1) fixes more than eight issues re‑
ported since the initial release of the 1912 LTSR.

Linux Virtual Delivery Agent (initial release)

Known issues in this release

Deprecation and removals

Citrix Product Subscription Advantage Eligibility Dates

Fixed issues in 1912 LTSR CU1

December 21, 2021

The following issues have been fixed since Linux Virtual Delivery Agent 1912 LTSR initial release:

• Linux VDAs might fail to display a list of logged‑on users. [CVADHELP‑13659]

• Attempts to generically redirect a removable USB drive to a Linux VDA might fail. The issue oc‑
curs when the USB drive is NTFS (New Technology File System) formatted. [CVADHELP‑13675]

• Linux VDAs might take a long time to initialize after you update them to Version 1909 or Version
1912. [CVADHELP‑13802]

• Linux VDAs that use Quest Authentication Services might fail to register with a Delivery Con‑
troller. The issue occurs when you are using the Linux VDA Version 1909, 1912 LTSR initial re‑
lease, and 2003. [CVADHELP‑14027]

• Linux VDAs might fail to reach frames per second as specified in the Target frame
rate (FramesPerSecond) setting. The issue occurs when a GPU is installed on a Linux VDA.
[CVADHELP‑14267]

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 11

Linux Virtual Delivery Agent 1912 LTSR

• The ctxjproxy service might fail to locate the LDAP server after you restart the system.
[CVADHELP‑14269]

• Linux VDAs might fail to register with Delivery Controllers. The issue occurs when the port
through which Linux VDAs communicate with Delivery Controllers is not 80. [CVADHELP‑14270]

• The .NET Core Runtime scripts might not be verified for authentication when you install a Linux
VDA. [CVADHELP‑14424]

About this release

May 1, 2020

What’s new

What’s new in 1912 LTSR

Version 1912 of the Linux VDA includes the following new features and enhancements:

Support for MCS on the AWS platform

You can use Machine Creation Services (MCS) to create Linux VMs on the AWS platform. For more
information, see Use MCS to create Linux VMs.

A currently running VDA can be used as the template

When using MCS to create Linux VMs, you can use a currently running VDA as the template and inherit
all its existing configurations. This running VDA can be installed manually or using easy install. For
more information, see Use MCS to create Linux VMs.

Client drive mapping: Support for large file transfers

Client drive mapping now supports transfers of files with the size of 4 GB and larger between the Linux
VDA and your client device. This enhancement requires your client to be running Citrix Workspace app
for Windows 1808 or later.
Note:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 12

Linux Virtual Delivery Agent 1912 LTSR

This release updates OpenJDK to Version 1.8.0 on all supported distributions.

Fixed issues in 1912 LTSR

December 21, 2021

The following issues have been fixed since Linux Virtual Delivery Agent 1909:

• On a 4K monitor, you might experience GPU performance issues associated with keystrokes and
refresh rates. [CVADHELP‑12661]

• A Linux VDI session might become unresponsive if the mouse and the keyboard are not focused
on the same window or the mouse fails to change focus. [CVADHELP‑12768]

• The Linux VDA registration might fail when you use virtual machines (VMs) that use only IPv6
addresses. [CVADHELP‑13103]

• When you set a policy to Default, the Linux VDA might not update the database. The issue oc‑
curs because higher priority policies cannot reset lower priority policies that are set to Default.
[CVADHELP‑13107]

• With the local keyboard layout feature enabled, keyboard layout synchronization might not
work in client‑side Hungarian language environments. When you start an application with DE
as a local setting, the language is synchronized, but it does not work for the Hungarian layout.
[CVADHELP‑13199]

• When you configure Xauthority to secure the communication between XClient and XServer,
only IPv4 addresses are added. IPv6 addresses are not added. [CVADHELP‑13255]

• On Ubuntu 18.04, attempts to create or update machine catalogs using Machine Creation Ser‑
vices (MCS) might fail. [CVADHELP‑13178]

Known issues

July 3, 2023

The following issues have been identified in this release:

• Non‑seamless published applications might exit shortly after launch. The issue occurs after a
Mutter upgrade to a version later than mutter‑3.28.3‑4. To work around the issue, use mutter‑
3.28.3‑4 or earlier. [LNXVDA‑6967]

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 13

Linux Virtual Delivery Agent 1912 LTSR

• The Linux VDA does not work as expected when you use NVIDIA GRID 3D cards without enabling
HDX 3D Pro. The issue occurs on RHEL 7.5 and earlier, SUSE 12.3 and earlier, and Ubuntu 16.04.
The reason is that multiple OpenGL libraries cannot coexist in the graphics systems of these
Linux distributions.

• An unexpected window appears during file download. The window does not affect the file down‑
load functionality and it automatically disappears after a while. [LNXVDA‑5646]

• The default settings of PulseAudio cause the sound server program to exit after 20 seconds of
inactivity. When PulseAudio exits, audio does not work. To work around this issue, set exit‑idle‑
time=‑1 in the /etc/pulse/daemon.conf file. [LNXVDA‑5464]

• libtcmalloc 4.3.0 in SUSE 12.3 might cause processes to exit unexpectedly.

• The ctxhdx service might exit unexpectedly on the Ubuntu 16.04 and SUSE 12.3 VDAs. The
issue occurs with the GNU C Library (glibc) Versions 2.22 through 2.24. The issue is fixed in
glibc 2.25. If you are using the SUSE 12.3 distribution, you can install the patch that SUSE
provides for fixing the issue. No fix is available for Ubuntu 16.04 at the time the Linux VDA 7.17
is released. [LNXVDA‑4481]

• Sessions cannot be launched in Citrix Workspace app for Linux when SSL encryption is enabled
and session reliability is disabled. [RFLNX‑1557]

• The indicator-datetime-service process does not consume the $TZ environment vari‑
able. When the client and session locate in different time zones, the unity panel on Ubuntu 16.04
Unity Desktop does not show the time of the client. [LNXVDA‑2128]

• Ubuntu graphics: In HDX 3D Pro, a black frame might appear around applications after resizing
the Desktop Viewer, or sometimes, the background can appear black.

• Printers created by the Linux VDA printing redirection might not be removed after logging out
of a session.

• CDM files are missing when a directory contains numerous files and subdirectories. This issue
might occur if the client side has too many files or directories.

• In this release, only UTF‑8 encoding is supported for non‑English languages.

• Citrix Workspace app for Android CAPS LOCK state might be reversed during session roaming.
The CAPS LOCK state can be lost when roaming an existing connection to Citrix Workspace app
for Android. As a workaround, use the Shift key on the extended keyboard to switch between
upper case and lower case.

• Shortcut keys with ALT do not always work when you connect to the Linux VDA using Citrix Work‑
space app for Mac. Citrix Workspace app for Mac sends AltGr for both left and right Options/Alt
keys by default. You can modify this behavior within the Citrix Workspace app settings but the
results vary with different applications.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 14

Linux Virtual Delivery Agent 1912 LTSR

• Registration fails when the Linux VDA is rejoined to the domain. The rejoining generates a fresh
set of Kerberos keys. But, the Broker might use a cached out‑of‑date VDA service ticket based
on the previous set of Kerberos keys. When the VDA tries to connect to the Broker, the Broker
might not be able to establish a return security context to the VDA. The usual symptom is that
the VDA registration fails.
This problem can eventually resolve itself when the VDA service ticket expires and is renewed.
But because service tickets are long‑lived, it can take a long time.
As a workaround, clear the Broker’s ticket cache. Restart the Broker or run the following com‑
mand on the Broker from a command prompt as Administrator:

1 klist -li 0x3e4 purge

2 <!--NeedCopy-->

This command purges all service tickets in the LSA cache held by the Network Service principal
under which the Citrix Broker Service runs. It removes service tickets for other VDAs and poten‑
tially other services. However, it is harmless –these service tickets can be reacquired from the
KDC when needed again.
• Audio plug‑n‑play is not supported. You can connect an audio capture device to the client ma‑
chine before starting to record audio in the ICA session. If a capture device is attached after the
audio recording application has started, the application might become unresponsive and you
must restart it. If a capture device is unplugged while recording, a similar issue might occur.
• Citrix Workspace app for Windows might experience audio distortion during audio recording.

Third party notices

October 20, 2021

Linux Virtual Delivery Agent 1912 LTSR (PDF Download)
This release of the Linux VDA can include third party software licensed under the terms defined in the
document.

Deprecation

October 13, 2021

The announcements in this article are intended to give you advanced notice of platforms, Citrix prod‑
ucts, and features that are being phased out so that you can make timely business decisions. Citrix

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 15

Linux Virtual Delivery Agent 1912 LTSR

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.

Deprecations and removals

The following table shows the platforms, Citrix products, and features that are deprecated or
removed.
Deprecated items are not removed immediately. Citrix continues to support them in this release but
they will be removed in a future Current Release.
Removed items are either removed, or are no longer supported, in the Linux VDA.

Item Deprecation announced in Removed in

Support for RHEL 6.9 1909 1909

Support for RHEL7.5, CentOS 1903 1903
7.5
Support for RHEL7.4, CentOS 1811 1811
7.4
Support for RHEL 6.8 1811 1811
Support for RHEL 7.3, CentOS 7.18 7.18
7.3
Support for RHEL 6.6 7.16 7.16
SUSE 11.4 7.16 7.16

System requirements

December 23, 2021

Linux distributions
Note:

System requirements for components not covered here (such as Citrix Workspace app) are de‑
scribed in their respective documentation sets.

Starting with the CU3 release, install .NET Core Runtime 3.1 as a prerequisite before you install

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 16

Linux Virtual Delivery Agent 1912 LTSR

the Linux VDA. For more information, see https://docs.microsoft.com/en‑us/dotnet/core/insta

ll/linux‑package‑managers.

The Linux VDA does not support SecureICA for encryption. Enabling SecureICA on the Linux VDA
causes session launch failure.

For information about using a Current Release (CR) in a Long Term Service (LTSR) environment
and other FAQs, see Knowledge Center article.

The Linux VDA supports the following Linux distributions:

Important:

When the support from your OS vendor expires, Citrix might be limited in its ability to remediate
problems.
For deprecated or removed platforms, see Deprecation.

• SUSE Linux Enterprise:

– Desktop 12 Service Pack 3

– Server 12 Service Pack 3

• Red Hat Enterprise Linux

– Workstation 7.7
– Workstation 6.10
– Server 7.7
– Server 6.10

• CentOS Linux

– CentOS 7.7
– CentOS 6.10

• Ubuntu Linux

– Ubuntu Desktop 18.04

– Ubuntu Server 18.04
– Ubuntu Live Server 18.04
– Ubuntu Desktop 16.04
– Ubuntu Server 16.04

• Pardus Linux

– Pardus 17 (For information on the supported feature scope, see Knowledge Center article
CTX238492).

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 17

Linux Virtual Delivery Agent 1912 LTSR

For a matrix of the Linux distributions and the Xorg versions that this version of the Linux VDA supports,
see the following table. For more information, see XorgModuleABIVersions.

Linux distribution Xorg version

RHEL 7.7, CentOS 7.7 1.20

RHEL 6.10, CentOS 6.10 1.17
Ubuntu 18.04 1.19
Ubuntu 16.04 1.18
SUSE 12.3 1.18
Pardus 17 1.19

Do not use HWE Xorg server 1.19 on Ubuntu 16.04.

In all cases, the supported processor architecture is x86‑64.

Note:

• If you install the Linux VDA 1912 LTSR Cumulative Update 2 (CU2) on CentOS 7.4 and want
to use it with the Citrix Virtual Apps and Desktops service, make sure to install the following
components before the VDA:

– Xorg 1.20.4
– SELinux policy 3.13.1‑268
– .NET Core Runtime 2.1
– GNOME 3.28.3 or later

• Gnome and KDE desktops are supported in SUSE, RHEL, and CentOS. Unity desktop is sup‑
ported in Ubuntu 16.04. Gnome desktop is supported in Ubuntu 18.04. At least one desktop
must be installed.

Citrix Virtual Desktops

The Linux VDA is compatible with all currently supported versions of Citrix Virtual Desktops. For infor‑
mation about the Citrix Virtual Desktops product lifecycle, and to find out when Citrix stops supporting
specific versions of products, see the Citrix Product Lifecycle Matrix.

The configuration process for Linux VDAs differs slightly from Windows VDAs. However, any Delivery
Controller farm is able to broker both Windows and Linux desktops.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 18

Linux Virtual Delivery Agent 1912 LTSR

Supported host platforms and virtualization environments

• Bare metal servers

• Citrix Hypervisor
• VMware ESX and ESXi
• Microsoft Hyper‑V
• Nutanix AHV
• Microsoft Azure Resource Manager
• Amazon Web Services (AWS)
• Google Cloud Platform (GCP)

Tip:

See the vendor’s documentation for the list of supported platforms.

Active Directory integration packages

The Linux VDA supports the following Active Directory integration packages or products:

• Samba Winbind
• Quest Authentication Services v4.1 or later
• Centrify DirectControl
• SSSD
• PBIS (compatible with RHEL 7 and Ubuntu)

Tip:

For the list of supported platforms, see the documentation from the vendors of the Active Direc‑
tory integration packages.

HDX 3D Pro

The HDX 3D Pro capabilities of Citrix Virtual Apps and Desktops let you deliver desktops and applica‑
tions that perform best using a Graphics Processing Unit (GPU) for hardware acceleration.

Hypervisors

For the Linux VDA, HDX 3D Pro is compatible with GPU pass‑through and GPU virtualization technolo‑
gies offered by the following hypervisors:

• Citrix Hypervisor
• VMware ESX and ESXi

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 19

Linux Virtual Delivery Agent 1912 LTSR

• Nutanix AHV

Note:

The hypervisors are compatible with certain Linux distributions.

GPUs

To learn which NVIDIA GPU cards your Linux distribution supports, go to the NVIDIA product support
matrix and check the Hypervisor or Bare‑Metal OS, Software Product Deployment, Hardware
Supported, and Guest OS Support columns. Ensure that you install the latest vGPU driver for your
GPU card. For more information, see NVIDIA Virtual GPU Software Supported GPUs.

The following are the GPU cards we have tested for GPU pass‑through and GPU virtualization sup‑
port.

GPUs we have tested for GPU pass‑through:

• NVIDIA GRID ‑ Tesla T4

• NVIDIA GTX750Ti
• NVIDIA GRID ‑ Tesla M60
• NVIDIA GRID ‑ K2
• NVIDIA GRID ‑ Tesla P40
• NVIDIA GRID ‑ Tesla P4
• NVIDIA GRID ‑ Tesla P100

GPUs we have tested for vGPU:

• NVIDIA GRID ‑ Tesla T4

• NVIDIA GRID ‑ Tesla V100
• NVIDIA GRID ‑ Tesla M60
• NVIDIA GRID ‑ Tesla M10
• NVIDIA GRID ‑ Tesla P40
• NVIDIA GRID ‑ Tesla P4
• NVIDIA GRID ‑ Tesla P100

Installation overview

September 8, 2021

This section guides you through the following procedures:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 20

Linux Virtual Delivery Agent 1912 LTSR

• Quick installation by using easy install (recommended for fresh installations)

• Manual installation based on various Linux distributions
• Use MCS to create Linux VMs
• Configure Delivery Controllers for XenDesktop 7.6 and earlier versions

Quick installation by using easy install (Recommended)

March 7, 2023
Important:

For fresh installations, we recommend you refer to this article for a quick installation. This article
steps through how to install and configure the Linux VDA by using easy install. Easy install saves
time and labor and is less error‑prone than manual installation. It helps you set up a running
environment of the Linux VDA by installing the necessary packages and customizing the config‑
uration files automatically.

Supported distributions

Winbind SSSD Centrify PBIS

RHEL 7.7 Yes Yes Yes Yes

RHEL 6.10 Yes Yes Yes No
CentOS 7.7 Yes Yes Yes Yes
CentOS 6.10 Yes Yes Yes No
Ubuntu 18.04 Yes Yes Yes Yes
Ubuntu 16.04 Yes Yes Yes Yes
SUSE 12.3 Yes No Yes No

Use easy install

To use this feature, do the following:

1. Prepare configuration information and the Linux machine.

2. Install the Linux VDA package.
Go to the Citrix Virtual Apps and Desktops download page. Expand the appropriate version of

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 21

Linux Virtual Delivery Agent 1912 LTSR

Citrix Virtual Apps and Desktops. Click Components to download the Linux VDA package that
matches your Linux distribution.
3. Set up the runtime environment to complete the Linux VDA installation.

Step 1: Prepare configuration information and the Linux machine

Collect the following configuration information needed for easy install:

• Host name ‑ Host name of the machine on which the Linux VDA is to be installed
• IP address of Domain Name Server
• IP address or string name of NTP Server
• Domain name ‑ The NetBIOS name of the domain
• Realm name ‑ The Kerberos realm name
• Fully Qualified Domain Name (FQDN) of the domain

Important:

• To install the Linux VDA, verify that the repositories are added correctly on the Linux ma‑
chine.
• To launch a session, verify that the X Window system and desktop environments are in‑
stalled.

Considerations

• The workgroup name, by default, is the domain name. To customize the workgroup in your
environment, do the following:

a. Create the /tmp/ctxinstall.conf file on the Linux VDA machine.

b. Add the workgroup=<your workgroup> line to the file and save your changes.

• Centrify does not support pure IPv6 DNS configuration. At least one DNS server using IPv4 is
required in /etc/resolv.conf for adclient to find AD services properly.

Log:

1 ADSITE : Check that this machine's subnet is in a site known by

AD : Failed
2 : This machine's subnet is not known by AD.
3 : We guess you should be in the site Site1.
4 <!--NeedCopy-->

This issue is unique to Centrify and its configuration. To resolve this issue, do the following:

a. Open Administrative Tools on the domain controller.

b. Select Active Directory Sites and Services.
c. Add a proper subnet address for Subnets.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 22

Linux Virtual Delivery Agent 1912 LTSR

• Easy install supports pure IPv6 as of Linux VDA 7.16. The following preconditions and limitations
apply:

– Your Linux repository must be configured to ensure that your machine can download re‑
quired packages over pure IPv6 networks.
– Centrify is not supported on pure IPv6 networks.

Note:

If your network is pure IPv6 and all your input is in proper IPv6 format, the VDA registers
with the Delivery Controller through IPv6. If your network has a hybrid IPv4 and IPv6 con‑
figuration, the type of the first DNS IP address determines whether IPv4 or IPv6 is used for
registration.

• If you choose Centrify as the method to join a domain, the ctxinstall.sh script requires the Cen‑
trify package. There are two ways for ctxinstall.sh to get the Centrify package:

– Easy install helps download the Centrify package from the Internet automatically. The
following are the URLs for each distribution:

RHEL: wget http://edge.centrify.com/products/centrify‑suite/2016‑update‑1/installers/c

entrify‑suite‑2016.1‑rhel4‑x86_64.tgz?_ga=1.178323680.558673738.1478847956

CentOS: wget http://edge.centrify.com/products/centrify‑suite/2016‑update‑1/installers

/centrify‑suite‑2016.1‑rhel4‑x86_64.tgz?_ga=1.186648044.558673738.1478847956

SUSE: wget http://edge.centrify.com/products/centrify‑suite/2016‑update‑1/installers/c

entrify‑suite‑2016.1‑suse10‑x86_64.tgz?_ga=1.10831088.558673738.1478847956

Ubuntu: wget http://edge.centrify.com/products/centrify‑suite/2016‑update‑1/installe

rs/centrify‑suite‑2016.1‑deb7‑x86_64.tgz?_ga=1.178323680.558673738.1478847956

– Fetch the Centrify package from a local directory. To designate the directory of the Centrify
package, do the following:

a. Create the /tmp/ctxinstall.conf file on the Linux VDA server if it does not exist.
b. Add the “centrifypkgpath=<path name>”line to the file.

For example:

1 cat /tmp/ctxinstall.conf
2 set "centrifypkgpath=/home/mydir"
3 ls -ls /home/mydir
4 9548 -r-xr-xr-x. 1 root root 9776688 May 13 2016
adcheck-rhel4-x86_64
5 4140 -r--r--r--. 1 root root 4236714 Apr 21 2016
centrifyda-3.3.1-rhel4-x86_64.rpm
6 33492 -r--r--r--. 1 root root 34292673 May 13 2016
centrifydc-5.3.1-rhel4-x86_64.rpm

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 23

Linux Virtual Delivery Agent 1912 LTSR

7 4 -rw-rw-r--. 1 root root 1168 Dec 1 2015

centrifydc-install.cfg
8 756 -r--r--r--. 1 root root 770991 May 13 2016
centrifydc-ldapproxy-5.3.1-rhel4-x86_64.rpm
9 268 -r--r--r--. 1 root root 271296 May 13 2016
centrifydc-nis-5.3.1-rhel4-x86_64.rpm
10 1888 -r--r--r--. 1 root root 1930084 Apr 12 2016
centrifydc-openssh-7.2p2-5.3.1-rhel4-x86_64.rpm
11 124 -rw-rw-r--. 1 root root 124543 Apr 19 2016
centrify-suite.cfg
12 0 lrwxrwxrwx. 1 root root 10 Jul 9 2012 install-
express.sh -> install.sh
13 332 -r-xr-xr--. 1 root root 338292 Apr 10 2016 install
.sh
14 12 -r--r--r--. 1 root root 11166 Apr 9 2015 release-
notes-agent-rhel4-x86_64.txt
15 4 -r--r--r--. 1 root root 3732 Aug 24 2015 release-
notes-da-rhel4-x86_64.txt
16 4 -r--r--r--. 1 root root 2749 Apr 7 2015 release-
notes-nis-rhel4-x86_64.txt
17 12 -r--r--r--. 1 root root 9133 Mar 21 2016 release-
notes-openssh-rhel4-x86_64.txt
18 <!--NeedCopy-->

• If you choose PBIS as the method to join a domain, the ctxinstall.sh script requires the PBIS
package. There are two ways for ctxinstall.sh to get the PBIS package:

– Easy install helps download the PBIS package from the Internet automatically. The follow‑
ing are the URLs for each distribution:

RHEL 7 / CentOS 7: wget https://github.com/BeyondTrust/pbis‑open/releases/download

/8.8.0/pbis‑open‑8.8.0.506.linux.x86_64.rpm.sh

Ubuntu: wget https://github.com/BeyondTrust/pbis‑open/releases/download/8.8.0/pbi

s‑open‑8.8.0.506.linux.x86_64.deb.sh

– Fetch a specific version of the PBIS package from the Internet. To do so, change the “pbis‑
DownloadPath”line in the /opt/Citrix/VDA/sbin/ctxinstall.sh file to designate the URL of
the PBIS package.

For an example, see the following screen capture:

Step 2: Prepare the hypervisor

Some changes are required when running the Linux VDA as a virtual machine on a supported hypervi‑
sor. Make the following changes according to the hypervisor platform in use. No changes are required
if you are running the Linux machine on bare metal hardware.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 24

Linux Virtual Delivery Agent 1912 LTSR

Fix time synchronization on Citrix Hypervisor

When the Citrix Hypervisor Time Sync feature is enabled, within each paravirtualized Linux VM you
experience issues with NTP and Citrix Hypervisor, both of which try to manage the system clock. To
avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization. No
changes are required in HVM mode.

On some Linux distributions, if you are running a paravirtualized Linux kernel with Citrix VM Tools
installed, you can check whether the Citrix Hypervisor Time Sync feature is present and enabled from
within the Linux VM:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns 0 or 1:

• 0 ‑ The time sync feature is enabled, and must be disabled.

• 1 ‑ The time sync feature is disabled, and no further action is required.

If the /proc/sys/xen/independent_wallclock file is not present, the following steps are not required.

If enabled, disable the time sync feature by writing 1 to the file:

1 sudo echo 1 > /proc/sys/xen/independent_wallclock

2 <!--NeedCopy-->

To make this change permanent and persistent after restart, edit the /etc/sysctl.conf file and add the
line:

xen.independent_wallclock = 1

To verify these changes, restart the system:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns the value 1.

Fix time synchronization on Microsoft Hyper‑V

The Linux VMs with Hyper‑V Linux Integration Services installed can apply the Hyper‑V time synchro‑
nization feature to use the time of the host operating system. To ensure that the system clock remains
accurate, you must enable this feature alongside the NTP services.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 25

Linux Virtual Delivery Agent 1912 LTSR

From the management operating system:

1. Open the Hyper‑V Manager console.

2. For the settings of a Linux VM, select Integration Services.
3. Ensure that Time synchronization is selected.

Note:

This approach is different from VMware and Citrix Hypervisor, where host time synchronization is
disabled to avoid conflicts with NTP. Hyper‑V time synchronization can coexist and supplement
NTP time synchronization.

Fix time synchronization on ESX and ESXi

When the VMware Time Synchronization feature is enabled, within each paravirtualized Linux VM you
experience issues with the NTP and the hypervisor, both of which try to synchronize the system clock.
To avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization.
If you are running a paravirtualized Linux kernel with VMware Tools installed:

1. Open the vSphere Client.

2. Edit settings for the Linux VM.
3. In the Virtual Machine Properties dialog, open the Options tab.
4. Select VMware Tools.
5. In the Advanced box, clear Synchronize guest time with host.

Step 3: Install .NET Core Runtime as a prerequisite

Before installing the Linux VDA, install .NET Core Runtime according to the instructions at https://do
cs.microsoft.com/en‑us/dotnet/core/install/linux‑package‑managers.

• For the 1912 LTSR initial release, CU1, and CU2, Install .NET Core Runtime 2.1.
• For CU3 and later releases, install .NET Core Runtime 3.1.

After installing .NET Core Runtime, run the which dotnet command to find your runtime path.
Based on the command output, set the .NET Core runtime binary path. For example, if the command
output is /aa/bb/dotnet, use /aa/bb as the .NET binary path.

Step 4: Download the Linux VDA package

Go to the Citrix Virtual Apps and Desktops download page. Expand the appropriate version of Citrix
Virtual Apps and Desktops and click Components to download the Linux VDA package that matches

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 26

Linux Virtual Delivery Agent 1912 LTSR

your Linux distribution.

Step 5: Install the Linux VDA package

To set up the environment for the Linux VDA, run the following commands.
For RHEL and CentOS distributions:

1 sudo yum -y localinstall <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

For Ubuntu distributions:

1 sudo dpkg -i <PATH>/<Linux VDA deb>

2 sudo apt-get install -f
3 <!--NeedCopy-->

For SUSE distributions:

1 zypper -i install <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

Step 6: Install NVIDIA GRID drivers

Enabling HDX 3D Pro requires you to install the NVIDIA GRID drivers on your hypervisor and on the VDA
machines.
To install and configure the NVIDIA GRID Virtual GPU Manager (the host driver) on the specific hyper‑
visors, see the following guides:

• Citrix Hypervisor
• VMware ESX

To install and configure the NVIDIA GRID guest VM drivers, perform the following general steps:

1. Ensure that the guest VM is shut down.

2. In the hypervisor control panel, allocate a GPU to the VM.
3. Start the VM.
4. Install the guest VM driver on the VM.

Step 7: Set up the runtime environment to complete the installation

Note:

Before setting up the runtime environment, ensure that the en_US.UTF-8 locale has been in‑
stalled in your OS. If the locale is not available in your OS, run the sudo locale-gen en_US

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 27

Linux Virtual Delivery Agent 1912 LTSR

.UTF-8 command.

After installing the Linux VDA package, configure the running environment by using the ctxinstall.sh
script. You can run the script in interactive mode or silent mode.

Note:

Easy install might seem unresponsive while it downloads .NET Core Runtime that is over 27 MB
in size. Check /var/log/ctxinstall.log for the downloading progress.

To do a manual configuration, run the following command and type the relevant parameter at each
prompt.

1 sudo /opt/Citrix/VDA/sbin/ctxinstall.sh
2 <!--NeedCopy-->

Silent mode:

To use easy install in silent mode, set the following environment variables before running ctxin‑
stall.sh.

• CTX_EASYINSTALL_HOSTNAME=host‑name –Denotes the host name of the Linux VDA server.

• CTX_EASYINSTALL_DNS=ip‑address‑of‑dns –IP address of DNS.
• CTX_EASYINSTALL_NTPS=address‑of‑ntps –IP address or string name of the NTP server.
• CTX_EASYINSTALL_DOMAIN=domain‑name –The NetBIOS name of the domain.
• CTX_EASYINSTALL_REALM=realm‑name –The Kerberos realm name.
• CTX_EASYINSTALL_FQDN=ad‑fqdn‑name
• CTX_EASYINSTALL_ADINTEGRATIONWAY=winbind | sssd | centrify | pbis –Denotes the Active
Directory integration method.
• CTX_EASYINSTALL_USERNAME=domain‑user‑name –Denotes the name of the domain user;
used to join the domain.
• CTX_EASYINSTALL_PASSWORD=password –Specifies the password of the domain user; used
to join the domain.

The ctxsetup.sh script uses the following variables:

• CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N –The Linux VDA supports specifying a Delivery

Controller name using a DNS CNAME record.
• CTX_XDL_DDC_LIST=’list‑ddc‑fqdns’–The Linux VDA requires a space‑separated list of Deliv‑
ery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Con‑
troller. At least one FQDN or CNAME must be specified.
• CTX_XDL_VDA_PORT=port‑number –The Linux VDA communicates with Delivery Controllers
through a TCP/IP port.
• CTX_XDL_REGISTER_SERVICE=Y | N –The Linux VDA services are started after machine startup.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 28

Linux Virtual Delivery Agent 1912 LTSR

• CTX_XDL_ADD_FIREWALL_RULES=Y | N –The Linux VDA services require incoming network

connections to be allowed through the system firewall. You can automatically open the re‑
quired ports (by default ports 80 and 1494) in the system firewall for the Linux VDA.
• CTX_XDL_HDX_3D_PRO=Y | N –The Linux VDA supports HDX 3D Pro, a set of GPU acceleration
technologies designed to optimize the virtualization of rich graphics applications. If HDX
3D Pro is selected, the VDA is configured for VDI desktops (single‑session) mode ‑ (that is,
CTX_XDL_VDI_MODE=Y).
• CTX_XDL_VDI_MODE=Y | N –Whether to configure the machine as a dedicated desktop delivery
model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set the
value to Y.
• CTX_XDL_SITE_NAME=dns‑name –The Linux VDA discovers LDAP servers through DNS. To
limit the DNS search results to a local Site, specify a DNS Site name. If unnecessary, set to
<none>.
• CTX_XDL_LDAP_LIST=’list‑ldap‑servers’ –The Linux VDA queries DNS to discover LDAP
servers. If DNS cannot provide LDAP service records, you can provide a space‑separated list of
LDAP FQDNs with LDAP ports. For example, ad1.mycompany.com:389. If unnecessary, set to
<none>.
• CTX_XDL_SEARCH_BASE=search‑base‑set –The Linux VDA queries LDAP through a search
base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com). To
improve search performance, you can specify a search base (for example, OU=VDI,DC=mycompany,DC=com).
If unnecessary, it can be set to <none>.
• CTX_XDL_FAS_LIST=’list‑fas‑servers’–The Federated Authentication Service (FAS) servers are
configured through AD Group Policy. The Linux VDA does not support AD Group Policy, but you
can provide a semicolon‑separated list of FAS servers instead. The sequence must be the same
as configured in AD Group Policy. If any server address is removed, fill its blank with the <none>
text string and do not modify the order of server addresses.
• CTX_XDL_DOTNET_RUNTIME_PATH=path‑to‑install‑dotnet‑runtime –The path to install
.NET Core Runtime for supporting the new broker agent service (ctxvda). The default path is
/usr/bin.
• CTX_XDL_START_SERVICE=Y | N –Whether or not the Linux VDA services are started when the
configuration is complete.

If any parameters are not set, the installation rolls back to interactive mode, with a prompt for user
input. When all parameters are already set through the environment variables, the ctxinstall.sh script
still prompts for user input for the path to install .NET Core Runtime.

In silent mode, you must run the following commands to set environment variables and then run the
ctxinstall.sh script.

1 export CTX_EASYINSTALL_HOSTNAME=host-name
2
3 export CTX_EASYINSTALL_DNS=ip-address-of-dns

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 29

Linux Virtual Delivery Agent 1912 LTSR

4
5 export CTX_EASYINSTALL_NTPS=address-of-ntps
6
7 export CTX_EASYINSTALL_DOMAIN=domain-name
8
9 export CTX_EASYINSTALL_REALM=realm-name
10
11 export CTX_EASYINSTALL_FQDN=ad-fqdn-name
12
13 export CTX_EASYINSTALL_ADINTEGRATIONWAY=winbind | sssd | centrify |
pbis
14
15 export CTX_EASYINSTALL_USERNAME=domain-user-name
16
17 export CTX_EASYINSTALL_PASSWORD=password
18
19 export CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N
20
21 export CTX_XDL_DDC_LIST='list-ddc-fqdns'
22
23 export CTX_XDL_VDA_PORT=port-number
24
25 export CTX_XDL_REGISTER_SERVICE=Y | N
26
27 export CTX_XDL_ADD_FIREWALL_RULES=Y | N
28
29 export CTX_XDL_HDX_3D_PRO=Y | N
30
31 export CTX_XDL_VDI_MODE=Y | N
32
33 export CTX_XDL_SITE_NAME=dns-site-name | '<none>'
34
35 export CTX_XDL_LDAP_LIST='list-ldap-servers' | '<none>'
36
37 export CTX_XDL_SEARCH_BASE=search-base-set | '<none>'
38
39 export CTX_XDL_FAS_LIST='list-fas-servers' | '<none>'
40
41 export CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime
42
43 export CTX_XDL_START_SERVICE=Y | N
44
45 sudo -E /opt/Citrix/VDA/sbin/ctxinstall.sh
46 <!--NeedCopy-->

When running the sudo command, type the ‑E option to pass the existing environment variables to the
new shell it creates. We recommend that you create a shell script file from the preceding commands
with #!/bin/bash as the first line.

Alternatively, you can specify all parameters by using a single command:

1 sudo CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N \
2

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 30

Linux Virtual Delivery Agent 1912 LTSR

3 CTX_XDL_DDC_LIST='list-ddc-fqdns' \
4
5 CTX_XDL_VDA_PORT=port-number \
6
7 CTX_XDL_REGISTER_SERVICE=Y|N \
8
9 CTX_XDL_ADD_FIREWALL_RULES=Y|N \
10
11 CTX_XDL_AD_INTEGRATION=1|2|3|4 \
12
13 CTX_XDL_HDX_3D_PRO=Y|N \
14
15 CTX_XDL_VDI_MODE=Y|N \
16
17 CTX_XDL_SITE_NAME=dns-name \
18
19 CTX_XDL_LDAP_LIST='list-ldap-servers' \
20
21 CTX_XDL_SEARCH_BASE=search-base-set \
22
23 CTX_XDL_FAS_LIST='list-fas-servers' \
24
25 CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime \
26
27 CTX_XDL_START_SERVICE=Y|N \
28
29 /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

Step 8: Run XDPing

We provide a command‑line utility, the Linux XDPing tool, to check for common configuration issues
with a Linux VDA environment. You can install the XDPing package on any machine running a sup‑
ported Linux distribution. XDPing does not require the Linux VDA package to be installed on the ma‑
chine. For more information about the tool, see Knowledge Center article CTX202015.

Step 9: Run the Linux VDA

Start the Linux VDA:

To start the Linux VDA services:

1 sudo /sbin/service ctxhdx start

2
3 sudo /sbin/service ctxvda start
4 <!--NeedCopy-->

Stop the Linux VDA:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 31

Linux Virtual Delivery Agent 1912 LTSR

To stop the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx stop
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor service daemon
restarts the services you stopped.

Restart the Linux VDA:

To restart the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx restart
4
5 sudo /sbin/service ctxvda start
6 <!--NeedCopy-->

Check the status of the Linux VDA:

To check the running status of the Linux VDA services:

1 sudo /sbin/service ctxvda status

2
3 sudo /sbin/service ctxhdx status
4 <!--NeedCopy-->

Step 10: Create the machine catalog in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating machine catalogs and adding Linux VDA machines is similar to the traditional
Windows VDA approach. For a more detailed description of how to complete these tasks, see Create
machine catalogs and Manage machine catalogs.

For creating machine catalogs that contain Linux VDA machines, there are a few restrictions that dif‑
ferentiate the process from creating machine catalogs for Windows VDA machines:

• For the operating system, select:

– The Multi‑session OS option for a hosted shared desktops delivery model.

– The Single‑session OS option for a VDI dedicated desktop delivery model.

• Do not mix Linux and Windows VDA machines in the same machine catalog.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 32

Linux Virtual Delivery Agent 1912 LTSR

Note:

Early versions of Citrix Studio did not support the notion of a “Linux OS.”However, selecting the
Windows Server OS or Server OS option implies an equivalent hosted shared desktops deliv‑
ery model. Selecting the Windows Desktop OS or Desktop OS option implies a single user per
machine delivery model.

Tip:

If you remove and rejoin a machine to the Active Directory domain, you must remove and add
the machine to the machine catalog again.

Step 11: Create the delivery group in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating a delivery group and adding machine catalogs containing Linux VDA ma‑
chines is almost identical to Windows VDA machines. For a more detailed description of how to com‑
plete these tasks, see Create Delivery Groups.

For creating delivery groups that contain Linux VDA machine catalogs, the following restrictions ap‑
ply:

• Ensure that the AD users and groups you select have been properly configured to log on to the
Linux VDA machines.
• Do not allow logon of unauthenticated (anonymous) users.
• Do not mix the delivery group with machine catalogs that contain Windows machines.

Important:

Publishing applications is supported with Linux VDA Version 1.4 and later. However, the Linux
VDA does not support the delivery of desktops and apps to the same machine.

For information about how to create machine catalogs and delivery groups, see Citrix Virtual Apps
and Desktops 7 1912 LTSR.

Troubleshooting

Use the information in this section to troubleshoot issues that can arise from using this feature.

Joining a domain by using SSSD fails

An error might occur when you attempt to join a domain, with the output similar to the following
(verify logs for screen printing):

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 33

Linux Virtual Delivery Agent 1912 LTSR

Step 6: join Domain!Enter ctxadmin's password:Failed to join domain:

failed to lookup DC info for domain 'CITRIXLAB.LOCAL'over rpc: The
network name cannot be found

/var/log/xdl/vda.log:

1 2016-11-04 02:11:52.317 [INFO ] - The Citrix Desktop Service

successfully obtained the following list of 1 delivery controller(s)
with which to register: 'CTXDDC.citrixlab.local (10.158.139.214)'.
2 2016-11-04 02:11:52.362 [ERROR] - RegistrationManager.
AttemptRegistrationWithSingleDdc: Failed to register with http://
CTXDDC.citrixlab.local:80/Citrix/CdsController/IRegistrar. Error:
General security error (An error occurred in trying to obtain a TGT:
Client not found in Kerberos database (6))
3 2016-11-04 02:11:52.362 [ERROR] - The Citrix Desktop Service cannot
connect to the delivery controller 'http://CTXDDC.citrixlab.local
:80/Citrix/CdsController/IRegistrar' (IP Address '10.158.139.214')
4 Check the following:- The system clock is in sync between this machine
and the delivery controller.
5 - The Active Directory provider (e.g. winbind daemon) service is
running and correctly configured.
6 - Kerberos is correctly configured on this machine.
7 If the problem persists, please refer to Citrix Knowledge Base article
CTX117248 for further information.
8 Error Details:
9 Exception 'General security error (An error occurred in trying to
obtain a TGT: Client not found in Kerberos database (6))' of type '
class javax.xml.ws.soap.SOAPFaultException'.
10 2016-11-04 02:11:52.362 [INFO ] - RegistrationManager.
AttemptRegistrationWithSingleDdc: The current time for this VDA is
Fri Nov 04 02:11:52 EDT 2016.
11 Ensure that the system clock is in sync between this machine and the
delivery controller.
12 Verify the NTP daemon is running on this machine and is correctly
configured.
13 2016-11-04 02:11:52.364 [ERROR] - Could not register with any
controllers. Waiting to try again in 120000 ms. Multi-forest - false
14 2016-11-04 02:11:52.365 [INFO ] - The Citrix Desktop Service failed to
register with any controllers in the last 470 minutes.
15 <!--NeedCopy-->

/var/log/messages:

Nov 4 02:15:27 RH-WS-68 [sssd[ldap_child[14867]]]: Failed to initialize

credentials using keytab [MEMORY:/etc/krb5.keytab]: Client 'RH-WS-68
$@CITRIXLAB.LOCAL'not found in Kerberos database. Unable to create
GSSAPI-encrypted LDAP connection.Nov 4 02:15:27 RH-WS-68 [sssd[
ldap_child[14867]]]: Client 'RH-WS-68$@CITRIXLAB.LOCAL'not found
in Kerberos database

To resolve this issue:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 34

Linux Virtual Delivery Agent 1912 LTSR

1. Run the rm -f /etc/krb5.keytab command.

2. Run the net ads leave $REALM -U $domain-administrator command.
3. Remove the machine catalog and delivery group on the Delivery Controller.
4. Run /opt/Citrix/VDA/sbin/ctxinstall.sh.
5. Create the machine catalog and delivery group on the Delivery Controller.

Ubuntu desktop sessions show a gray screen

This issue occurs when you launch a session that is then blocked in a blank desktop. In addition, the
console of the machine also shows a gray screen when you log on by using a local user account.

To resolve this issue:

1. Run the sudo apt-get update command.

2. Run the sudo apt-get install unity lightdm command.
3. Add the following line to /etc/lightdm/lightdm.conf:
greeter‑show‑manual‑login=true

Attempts to launch Ubuntu desktop sessions fail due to a missing home directory

/var/log/xdl/hdx.log:

1 2016-11-02 13:21:19.015 <P22492:S1> citrix-ctxlogin: StartUserSession:

failed to change to directory(/home/CITRIXLAB/ctxadmin) errno(2)
2
3 2016-11-02 13:21:19.017 <P22227> citrix-ctxhdx: logSessionEvent:
Session started for user ctxadmin.
4
5 2016-11-02 13:21:19.023 <P22492:S1> citrix-ctxlogin: ChildPipeCallback:
Login Process died: normal.
6
7 2016-11-02 13:21:59.217 <P22449:S1> citrix-ctxgfx: main: Exiting
normally.
8 <!--NeedCopy-->

Tip:

The root cause of this issue is that the home directory is not created for the domain administrator.

To resolve this issue:

1. From a command line, type pam‑auth‑update.

2. In the resulting dialog, verify that Create home directory login is selected.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 35

Linux Virtual Delivery Agent 1912 LTSR

Session does not launch or ends quickly with dbus error

/var/log/messages (for RHEL or CentOS):

1 Oct 27 04:17:16 CentOS7 citrix-ctxhdx[8978]: Session started for user

CITRIXLAB\ctxadmin.
2
3 Oct 27 04:17:18 CentOS7 kernel: traps: gnome-session[19146] trap int3
ip:7f89b3bde8d3 sp:7fff8c3409d0 error:0
4
5 Oct 27 04:17:18 CentOS7 gnome-session[19146]: ERROR: Failed to connect
to system bus: Exhausted all available authentication mechanisms (
tried: EXTERNAL, DBUS_COOKIE_SHA1, ANONYMOUS) (available: EXTERNAL,
DBUS_COOKIE_SHA1, ANONYMOUS)#012aborting...
6
7 Oct 27 04:17:18 CentOS7 gnome-session: gnome-session[19146]: ERROR:
Failed to connect to system bus: Exhausted all available
authentication mechanisms (tried: EXTERNAL, DBUS_COOKIE_SHA1,
ANONYMOUS) (available: EXTERNAL, DBUS_COOKIE_SHA1, ANONYMOUS)
8
9 Oct 27 04:17:18 CentOS7 gnome-session: aborting...
10
11 Oct 27 04:17:18 CentOS7 citrix-ctxgfx[18981]: Exiting normally.
12
13 Oct 27 04:17:18 CentOS7 citrix-ctxhdx[8978]: Session stopped for user
CITRIXLAB\ctxadmin.
14 <!--NeedCopy-->

Or, alternately for Ubuntu distributions, use the log /var/log/syslog:

1 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25326]: [pulseaudio] pid.c:

Stale PID file, overwriting.
2
3 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25326]: [pulseaudio] bluez5-
util.c: Failed to get D-Bus connection: Did not receive a reply.
Possible causes include: the remote application did not send a reply
, the message bus security policy blocked the reply, the reply
timeout expired, or the network connection was broken.
4
5 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25326]: [pulseaudio] hashmap
.c: Assertion 'h' failed at pulsecore/hashmap.c:116, function
pa_hashmap_free(). Aborting.
6

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 36

Linux Virtual Delivery Agent 1912 LTSR

7 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25352]: [pulseaudio] core-

util.c: Failed to connect to system bus: Did not receive a reply.
Possible causes include: the remote application did not send a reply
, the message bus security policy blocked the reply, the reply
timeout expired, or the network connection was broken.
8
9 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25352]: message repeated 10
times: [ [pulseaudio] core-util.c: Failed to connect to system bus:
Did not receive a reply. Possible causes include: the remote
application did not send a reply, the message bus security policy
blocked the reply, the reply timeout expired, or the network
connection was broken.]
10
11 Nov 3 11:03:52 user01-HVM-domU pulseaudio[25352]: [pulseaudio] pid.c:
Daemon already running.Nov 3 11:03:58 user01-HVM-domU citrix-ctxgfx
[24693]: Exiting normally
12 <!--NeedCopy-->

Some groups or modules do not take effect until a restart. If the dbus error messages appear in the
log, we recommend that you restart the system and retry.

SELinux prevents SSHD from accessing the home directory

The user can launch a session but cannot log on.

/var/log/ctxinstall.log:

1 Jan 25 23:30:31 yz-rhel72-1 setroubleshoot[3945]: SELinux is preventing

/usr/sbin/sshd from setattr access on the directory /root. For
complete SELinux messages. run sealert -l 32f52c1f-8ff9-4566-a698
-963a79f16b81
2
3 Jan 25 23:30:31 yz-rhel72-1 python[3945]: SELinux is preventing /usr/
sbin/sshd from setattr access on the directory /root.
4
5 ***** Plugin catchall_boolean (89.3 confidence) suggests
******************
6
7 If you want to allow polyinstantiation to enabled
8
9 Then you must tell SELinux about this by enabling the '
polyinstantiation_enabled' boolean.
10
11 You can read 'None' man page for more details.
12
13 Do
14
15 setsebool -P polyinstantiation_enabled 1
16
17 ***** Plugin catchall (11.6 confidence) suggests
**************************
18

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 37

Linux Virtual Delivery Agent 1912 LTSR

19 If you believe that sshd should be allowed setattr access on the root
directory by default.
20
21 Then you should report this as a bug.
22
23 You can generate a local policy module to allow this access.
24
25 Do
26
27 allow this access for now by executing:
28
29 # grep sshd /var/log/audit/audit.log | audit2allow -M mypol
30
31 # semodule -i mypol.pp
32 <!--NeedCopy-->

To resolve this issue:

1. Disable SELinux by making the following change to /etc/selinux/config.

SELINUX=disabled
2. Restart the VDA.

Install Linux Virtual Delivery Agent for RHEL/CentOS manually

June 10, 2022

Important:

For fresh installations, we recommend you use easy install for a quick installation. Easy install
saves time and labor and is less error‑prone than the manual installation detailed in this article.

Step 1: Prepare RHEL 7/CentOS 7, RHEL 6/CentOS 6 for VDA installation

Step 1a: Verify the network configuration

Ensure that the network is connected and configured correctly. For example, you must configure the
DNS server on the Linux VDA.

Step 1b: Set the host name

To ensure that the host name of the machine is reported correctly, change the /etc/hostname file (for
RHEL 7 and CentOS 7) or the /etc/sysconfig/network file (for RHEL 6 and CentOS 6) to contain only
the host name of the machine.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 38

Linux Virtual Delivery Agent 1912 LTSR

hostname

Step 1c: Assign a loopback address to the host name

To ensure that the DNS domain name and Fully Qualified Domain Name (FQDN) of the machine are
reported back correctly, change the following line of the /etc/hosts file to include the FQDN and host
name as the first two entries:

127.0.0.1 <hostname-fqdn> <hostname> localhost localhost.localdomain

localhost4 localhost4.localdomain4

For example:

127.0.0.1 vda01.example.com vda01 localhost localhost.localdomain

localhost4 localhost4.localdomain4

Remove any other references to hostname‑fqdn or hostname from other entries in the file.

Note:

The Linux VDA currently does not support NetBIOS name truncation. Therefore, the host name
must not exceed 15 characters.

Tip:

Use a–z, A–Z, 0–9, and hyphen (‑) characters only. Avoid underscores (_), spaces, and other sym‑
bols. Do not start a host name with a number and do not end with a hyphen. This rule also
applies to Delivery Controller host names.

Step 1d: Check the host name

Verify that the host name is set correctly:

1 hostname
2 <!--NeedCopy-->

This command returns only the machine’s host name and not its fully qualified domain name
(FQDN).

Verify that the FQDN is set correctly:

1 hostname -f
2 <!--NeedCopy-->

This command returns the FQDN of the machine.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 39

Linux Virtual Delivery Agent 1912 LTSR

Step 1e: Check name resolution and service reachability

Verify that you can resolve the FQDN and ping the domain controller and Delivery Controller:

1 nslookup domain-controller-fqdn
2
3 ping domain-controller-fqdn
4
5 nslookup delivery-controller-fqdn
6
7 ping delivery-controller-fqdn
8 <!--NeedCopy-->

If you cannot resolve the FQDN or ping either of these machines, review the steps before proceed‑
ing.

Step 1f: Configure clock synchronization

Maintaining accurate clock synchronization between the VDAs, Delivery Controllers, and domain con‑
trollers is crucial. Hosting the Linux VDA as a virtual machine can cause clock skew problems. For this
reason, synchronizing time with a remote time service is preferred.

RHEL 6.x and earlier releases use the NTP daemon (ntpd) for clock synchronization, whereas an RHEL
7.x default environment uses the newer Chrony daemon (chronyd) instead. The configuration and
operational process between the two services is similar.

Configure the NTP service (RHEL 6/CentOS 6 only) As a root user, edit /etc/ntp.conf and add a
server entry for each remote time server:

1 server peer1-fqdn-or-ip-address iburst

2
3 server peer2-fqdn-or-ip-address iburst
4 <!--NeedCopy-->

In a typical deployment, synchronize time from the local domain controllers and not directly from pub‑
lic NTP pool servers. Add a server entry for each Active Directory domain controller in the domain.

Remove any other server entries listed including loopback IP address, localhost, and public server
*.pool.ntp.org entries.

Save changes and restart the NTP daemon:

1 sudo /sbin/service ntpd restart

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 40

Linux Virtual Delivery Agent 1912 LTSR

Configure the Chrony service (RHEL 7/CentOS 7 only) As a root user, edit /etc/chrony.conf and
add a server entry for each remote time server:

1 server peer1-fqdn-or-ip-address iburst

2
3 server peer2-fqdn-or-ip-address iburst
4 <!--NeedCopy-->

In a typical deployment, synchronize time from the local domain controllers and not directly from pub‑
lic NTP pool servers. Add a server entry for each Active Directory domain controller in the domain.

Remove any other server entries listed including loopback IP address, localhost, and public server
*.pool.ntp.org entries.

Save changes and restart the Chrony daemon:

1 sudo /sbin/service chronyd restart

2 <!--NeedCopy-->

Step 1g: Install OpenJDK

The Linux VDA depends on OpenJDK. Typically, the runtime environment is installed as part of the
operating system installation.

Confirm the correct version:

1 sudo yum info java-1.8.0-openjdk

2 <!--NeedCopy-->

The prepackaged OpenJDK might be an earlier version. Update to the latest version as required:

1 sudo yum -y update java-1.8.0-openjdk

2 <!--NeedCopy-->

Open a new shell and verify the version of Java:

1 java -version
2 <!--NeedCopy-->

Tip:

To avoid registration failure with the Delivery Controller, ensure that you installed only OpenJDK
1.8.0. Remove all other versions of Java from your system.

Step 1h: Install PostgreSQL

The Linux VDA requires either PostgreSQL 8.4 or later on RHEL 6 or PostgreSQL 9.2 or later on RHEL
7.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 41

Linux Virtual Delivery Agent 1912 LTSR

Install the following packages:

1 sudo yum -y install postgresql-server

2
3 sudo yum -y install postgresql-jdbc
4 <!--NeedCopy-->

The following post‑installation step is required to initialize the database and to ensure that the ser‑
vice starts upon machine startup. This action creates database files under /var/lib/pgsql/data. The
command differs between PostgreSQL 8 and 9:

• RHEL 7 only: PostgreSQL 9

1 sudo postgresql-setup initdb

2 <!--NeedCopy-->

• RHEL 6 only: PostgreSQL 8

1 sudo /sbin/service postgresql initdb

2 <!--NeedCopy-->

Step 1i: Start PostgreSQL

Start the service upon machine startup and start the service immediately:

• RHEL 7 only: PostgreSQL 9

1 sudo systemctl enable postgresql

2
3 sudo systemctl start postgresql
4 <!--NeedCopy-->

• RHEL 6 only: PostgreSQL 8

1 sudo /sbin/chkconfig postgresql on

2
3 sudo /sbin/service postgresql start
4 <!--NeedCopy-->

Check the version of PostgreSQL by using:

1 psql --version
2 <!--NeedCopy-->

Verify that the data directory is set by using the psql command‑line utility:

1 sudo -u postgres psql -c 'show data_directory'

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 42

Linux Virtual Delivery Agent 1912 LTSR

Important:

In this release, a new dependency is added for gperftools-libs, but it does not exist
in the original repository. Add the repository by using the sudo rpm -ivh https://
dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
command.
Only RHEL 6/CentOS 6 is impacted. Run the command before installing the Linux VDA package.

Step 2: Prepare the hypervisor

Some changes are required when running the Linux VDA as a virtual machine on a supported hypervi‑
sor. Make the following changes according to the hypervisor platform in use. No changes are required
if you are running the Linux machine on bare metal hardware.

Fix time synchronization on Citrix Hypervisor

When the Citrix Hypervisor Time Sync feature is enabled, within each paravirtualized Linux VM you
experience issues with NTP and Citrix Hypervisor, both of which try to manage the system clock. To
avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization. No
changes are required in HVM mode.

On some Linux distributions, if you are running a paravirtualized Linux kernel with Citrix VM Tools
installed, you can check whether the Citrix Hypervisor Time Sync feature is present and enabled from
within the Linux VM:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns 0 or 1:

• 0 ‑ The time sync feature is enabled, and must be disabled.

• 1 ‑ The time sync feature is disabled, and no further action is required.

If the /proc/sys/xen/independent_wallclock file is not present, the following steps are not required.

If enabled, disable the time sync feature by writing 1 to the file:

1 sudo echo 1 > /proc/sys/xen/independent_wallclock

2 <!--NeedCopy-->

To make this change permanent and persistent after restart, edit the /etc/sysctl.conf file and add the
line:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 43

Linux Virtual Delivery Agent 1912 LTSR

xen.independent_wallclock = 1

To verify these changes, restart the system:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns the value 1.

Fix time synchronization on Microsoft Hyper‑V

The Linux VMs with Hyper‑V Linux Integration Services installed can apply the Hyper‑V time synchro‑
nization feature to use the time of the host operating system. To ensure that the system clock remains
accurate, you must enable this feature alongside the NTP services.

From the management operating system:

1. Open the Hyper‑V Manager console.

2. For the settings of a Linux VM, select Integration Services.
3. Ensure that Time synchronization is selected.

Note:

This approach is different from VMware and Citrix Hypervisor, where host time synchronization is
disabled to avoid conflicts with NTP. Hyper‑V time synchronization can coexist and supplement
NTP time synchronization.

Fix time synchronization on ESX and ESXi

When the VMware Time Synchronization feature is enabled, within each paravirtualized Linux VM you
experience issues with the NTP and the hypervisor, both of which try to synchronize the system clock.
To avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization.

If you are running a paravirtualized Linux kernel with VMware Tools installed:

1. Open the vSphere Client.

2. Edit settings for the Linux VM.
3. In the Virtual Machine Properties dialog, open the Options tab.
4. Select VMware Tools.
5. In the Advanced box, clear Synchronize guest time with host.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 44

Linux Virtual Delivery Agent 1912 LTSR

Step 3: Add the Linux virtual machine (VM) to the Windows domain

The Linux VDA supports several methods for adding Linux machines to the Active Directory (AD) do‑
main:

• Samba Winbind
• Quest Authentication Services
• Centrify DirectControl
• SSSD
• PBIS (compatible with RHEL 7 only)

Follow instructions based on your chosen method.

Note:

Session launches might fail when the same user name is used for the local account in the Linux
VDA and the account in AD.

Samba Winbind

Install or update the required packages:

1 sudo yum -y install samba-winbind samba-winbind-clients krb5-

workstation authconfig oddjob-mkhomedir
2 <!--NeedCopy-->

Enable Winbind daemon to start upon machine startup The Winbind daemon must be configured
to start upon machine startup:

1 sudo /sbin/chkconfig winbind on

2 <!--NeedCopy-->

Configure Winbind Authentication Configure the machine for Kerberos authentication by using
Winbind:

1 sudo authconfig --disablecache --disablesssd --disablesssdauth --

enablewinbind --enablewinbindauth --disablewinbindoffline --
smbsecurity=ads --smbworkgroup=domain --smbrealm=REALM --krb5realm=
REALM --krb5kdc=fqdn-of-domain-controller --winbindtemplateshell=/
bin/bash --enablemkhomedir --updateall
2 <!--NeedCopy-->

Where REALM is the Kerberos realm name in uppercase and domain is the NetBIOS name of the do‑
main.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 45

Linux Virtual Delivery Agent 1912 LTSR

If DNS‑based lookup of the KDC server and realm name is required, add the following two options to
the previous command:

--enablekrb5kdcdns --enablekrb5realmdns

Ignore any errors returned from the authconfig command about the winbind service failing to
start. The errors can occur when authconfig tries to start the winbind service without the ma‑
chine yet being joined to the domain.

Open /etc/samba/smb.conf and add the following entries under the [Global] section, but after the
section generated by the authconfig tool:

kerberos method = secrets and keytab

winbind refresh tickets = true

The Linux VDA requires the system keytab file /etc/krb5.keytab to authenticate and register with the
Delivery Controller. The previous kerberos method setting forces Winbind to create the system keytab
file when the machine is first joined to the domain.

Join Windows domain Your domain controller must be reachable and you must have an Active Di‑
rectory user account with permissions to add computers to the domain:

1 sudo net ads join REALM -U user

2 <!--NeedCopy-->

REALM is the Kerberos realm name in uppercase, and user is a domain user who has permissions to
add computers to the domain.

Configure PAM for Winbind By default, the configuration for the Winbind PAM module
(pam_winbind) does not enable Kerberos ticket caching and home directory creation. Open
/etc/security/pam_winbind.conf and add or change the following entries under the [Global]
section:

krb5_auth = yes
krb5_ccache_type = FILE
mkhomedir = yes

Ensure that any leading semi‑colons from each setting are removed. These changes require restarting
the Winbind daemon:

1 sudo /sbin/service winbind restart

2 <!--NeedCopy-->

Tip:

The winbind daemon stays running only if the machine is joined to a domain.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 46

Linux Virtual Delivery Agent 1912 LTSR

Open /etc/krb5.conf and change the following setting under the [libdefaults] section from KEYRING
to FILE type:

default_ccache_name = FILE:/tmp/krb5cc_%{ uid }

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory.

Run the net ads command of Samba to verify that the machine is joined to a domain:

1 sudo net ads testjoin

2 <!--NeedCopy-->

Run the following command to verify extra domain and computer object information:

1 sudo net ads info

2 <!--NeedCopy-->

Verify Kerberos configuration To ensure that Kerberos is configured correctly for use with the
Linux VDA, verify that the system keytab file has been created and contains valid keys:

1 sudo klist -ke

2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

1 sudo kinit -k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

Verify that the TGT ticket for the machine account has been cached using:

1 sudo klist
2 <!--NeedCopy-->

Examine the account details of the machine using:

1 sudo net ads status

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 47

Linux Virtual Delivery Agent 1912 LTSR

Verify user authentication Use the wbinfo tool to verify that domain users can authenticate with
the domain:

1 wbinfo --krb5auth=domain\\username%password
2 <!--NeedCopy-->

The domain specified here is the AD domain name, not the Kerberos realm name. For the bash shell,
the backslash (\) character must be escaped with another backslash. This command returns a mes‑
sage indicating success or failure.

To verify that the Winbind PAM module is configured correctly, log on to the Linux VDA using a domain
user account that has not been used before.

1 ssh localhost -l domain\\username

2 id -u
3 <!--NeedCopy-->

Verify that the tickets in the Kerberos credential cache are valid and not expired:

1 klist
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

A similar test can be performed by logging on to the Gnome or KDE console directly. Proceed to Step
6: Install the Linux VDA after the domain joining verification.

Quest Authentication Services

Configure Quest on domain controller Assume that you have installed and configured the Quest
software on the Active Directory domain controllers, and have been granted administrative privileges
to create computer objects in Active Directory.

Enable domain users to log on to Linux VDA machines To enable domain users to establish HDX
sessions on a Linux VDA machine:

1. In the Active Directory Users and Computers management console, open Active Directory user
properties for that user account.
2. Select the Unix Account tab.
3. Check Unix‑enabled.
4. Set the Primary GID Number to the group ID of an actual domain user group.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 48

Linux Virtual Delivery Agent 1912 LTSR

Note:

These instructions are equivalent for setting up domain users for logon using the console, RDP,
SSH, or any other remoting protocol.

Configure Quest on Linux VDA

Work around SELinux policy enforcement The default RHEL environment has SELinux fully en‑
forced. This enforcement interferes with the Unix domain socket IPC mechanisms used by Quest, and
prevents domain users from logging on.

The convenient way to work around this issue is to disable SELinux. As a root user, edit /etc/selinux/‑
config and change the SELinux setting:

SELINUX=permissive

This change requires a machine restart:

1 reboot
2 <!--NeedCopy-->

Important:

Use this setting carefully. Reenabling SELinux policy enforcement after disabling can cause a
complete lockout, even for the root user and other local users.

Configure VAS daemon Auto‑renewal of Kerberos tickets must be enabled and disconnected. Au‑
thentication (offline logon) must be disabled.

1 sudo /opt/quest/bin/vastool configure vas vasd auto-ticket-renew-

interval 32400
2
3 sudo /opt/quest/bin/vastool configure vas vas_auth allow-disconnected-
auth false
4 <!--NeedCopy-->

This command sets the renewal interval to nine hours (32,400 seconds) which is one hour less than
the default 10‑hour ticket lifetime. Set this parameter to a lower value on systems with a shorter ticket
lifetime.

Configure PAM and NSS To enable domain user logon through HDX and other services such as su,
ssh, and RDP, run the following commands to manually configure PAM and NSS:

1 sudo /opt/quest/bin/vastool configure pam

2

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 49

Linux Virtual Delivery Agent 1912 LTSR

3 sudo /opt/quest/bin/vastool configure nss

4 <!--NeedCopy-->

Join Windows domain Join the Linux machine to the Active Directory domain using the Quest
vastool command:

1 sudo /opt/quest/bin/vastool -u user join domain-name

2 <!--NeedCopy-->

The user is any domain user who has permissions to join computers to the Active Directory domain.
The domain‑name is the DNS name of the domain, for example, example.com.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a Quest‑joined Linux machine
is on the domain:

1 sudo /opt/quest/bin/vastool info domain

2 <!--NeedCopy-->

If the machine is joined to a domain, this command returns the domain name. If the machine is not
joined to any domain, the following error appears:
ERROR: No domain could be found.
ERROR: VAS_ERR_CONFIG: at ctx.c:414 in _ctx_init_default_realm
default_realm not configured in vas.conf. Computer may not be joined
to domain

Verify user authentication To verify that Quest can authenticate domain users through PAM, log
on to the Linux VDA using a domain user account that has not been used before.

1 ssh localhost -l domain\\username

2 id -u
3 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the UID returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Verify that the tickets in the Kerberos credential cache are valid and not expired:

1 /opt/quest/bin/vastool klist
2 <!--NeedCopy-->

Exit the session.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 50

Linux Virtual Delivery Agent 1912 LTSR

1 exit
2 <!--NeedCopy-->

A similar test can be performed by logging on to the Gnome or KDE console directly. Proceed to Step
6: Install the Linux VDA after the domain joining verification.

Centrify DirectControl

Join Windows domain With the Centrify DirectControl Agent installed, join the Linux machine to
the Active Directory domain using the Centrify adjoin command:

1 su –
2 adjoin -w -V -u user domain-name
3 <!--NeedCopy-->

The user parameter is any Active Directory domain user who has permissions to join computers to
the Active Directory domain. The domain‑name is the name of the domain to join the Linux machine
to.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a Centrify‑joined Linux machine
is on the domain:

1 su –
2 adinfo
3 <!--NeedCopy-->

Verify that the Joined to domain value is valid and the CentrifyDC mode returns connected. If the
mode remains stuck in the starting state, then the Centrify client is experiencing server connection or
authentication problems.

More comprehensive system and diagnostic information is available using:

1 adinfo --sysinfo all

2 adinfo – diag
3 <!--NeedCopy-->

Test connectivity to the various Active Directory and Kerberos services.

1 adinfo --test
2 <!--NeedCopy-->

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 51

Linux Virtual Delivery Agent 1912 LTSR

SSSD

If you are using SSSD, follow the instructions in this section. This section includes instructions for
joining a Linux VDA machine to a Windows domain and provides guidance for configuring Kerberos
authentication.

To set up SSSD on RHEL and CentOS, do the following:

1. Join the domain and create host keytab

2. Set up SSSD
3. Configure NSS/PAM
4. Verify the Kerberos configuration
5. Verify user authentication

Required software The Active Directory provider was first introduced with SSSD Version 1.9.0. If
you are using an earlier version, follow the instructions provided in configuring the LDAP provider
with Active Directory.

The following environments have been tested and verified when you use the instructions included in
this article:

• RHEL 7.7 and later

• CentOS 7.7 and later

Join the domain and create host keytab SSSD does not provide Active Directory client functions
for joining the domain and managing the system keytab file. You can use adcli, realmd, or Samba
instead.

The information in this section describes the Samba approach only. For adcli and realmd, see the
RHEL or CentOS documentation. These steps must be followed before configuring SSSD.

Install or update the required packages:

1 sudo yum -y install krb5-workstation authconfig oddjob-mkhomedir samba-

common-tools
2 <!--NeedCopy-->

On the Linux client with properly configured files:

• /etc/krb5.conf
• /etc/samba/smb.conf:

Configure the machine for Samba and Kerberos authentication:

1 sudo authconfig --smbsecurity=ads --smbworkgroup=domain --smbrealm=

REALM --krb5realm=REALM --krb5kdc=fqdn-of-domain-controller --update

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 52

Linux Virtual Delivery Agent 1912 LTSR

2 <!--NeedCopy-->

Where REALM is the Kerberos realm name in uppercase and domain is the short NetBIOS name of the
Active Directory domain.

If DNS‑based lookup of the KDC server and realm name is required, add the following two options to
the preceding command:

--enablekrb5kdcdns --enablekrb5realmdns

Open /etc/samba/smb.conf and add the following entries under the [Global] section, but after the
section generated by the authconfig tool:

kerberos method = secrets and keytab

Join the Windows domain. Ensure that your domain controller is reachable and you have an Active
Directory user account with permissions to add computers to the domain:

1 sudo net ads join REALM -U user

2 <!--NeedCopy-->

REALM is the Kerberos realm name in uppercase and user is a domain user who has permissions to
add computers to the domain.

Set up SSSD Setting up SSSD consists of the following steps:

• Install the sssd‑ad package on the Linux VDA.

• Make configuration changes to various files (for example, sssd.conf).
• Start the sssd service.

An example sssd.conf configuration (extra options can be added as needed):

1 [sssd]
2 config_file_version = 2
3 domains = ad.example.com
4 services = nss, pam
5
6 [domain/ad.example.com]
7 # Uncomment if you need offline logins
8 # cache_credentials = true
9
10 id_provider = ad
11 auth_provider = ad
12 access_provider = ad
13 ldap_id_mapping = true
14 ldap_schema = ad
15
16 # Should be specified as the lower-case version of the long version of
the Active Directory domain.
17 ad_domain = ad.example.com

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 53

Linux Virtual Delivery Agent 1912 LTSR

18
19 # Kerberos settings
20 krb5_ccachedir = /tmp
21 krb5_ccname_template = FILE:%d/krb5cc_%U
22
23 # Uncomment if service discovery is not working
24 # ad_server = server.ad.example.com
25
26 # Comment out if the users have the shell and home dir set on the AD
side
27 default_shell = /bin/bash
28 fallback_homedir = /home/%d/%u
29
30 # Uncomment and adjust if the default principal SHORTNAME$@REALM is not
available
31 # ldap_sasl_authid = host/client.ad.example.com@AD.EXAMPLE.COM
32 <!--NeedCopy-->

Replace ad.example.com, server.ad.example.com with the corresponding values. For more details,
see sssd‑ad(5) ‑ Linux man page.

Set the file ownership and permissions on sssd.conf:

chown root:root /etc/sssd/sssd.conf

chmod 0600 /etc/sssd/sssd.conf
restorecon /etc/sssd/sssd.conf

Configure NSS/PAM RHEL/CentOS:

Use authconfig to enable SSSD. Install oddjob‑mkhomedir to ensure that the home directory cre‑
ation is compatible with SELinux:

1 authconfig --enablesssd --enablesssdauth --enablemkhomedir – -update

2
3 sudo service sssd start
4
5 sudo chkconfig sssd on
6 <!--NeedCopy-->

Verify Kerberos configuration Verify that the system keytab file has been created and contains
valid keys:

1 sudo klist -ke

2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 54

Linux Virtual Delivery Agent 1912 LTSR

1 sudo kinit – k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

Verify that the TGT ticket for the machine account has been cached using:

1 sudo klist
2 <!--NeedCopy-->

Verify user authentication Use the getent command to verify that the logon format is supported
and the NSS works:

1 sudo getent passwd DOMAIN\\username

2 <!--NeedCopy-->

The DOMAIN parameter indicates the short version domain name. If another logon format is needed,
verify by using the getent command first.

The supported logon formats are:

• Down‑level logon name: DOMAIN\username

• UPN: username@domain.com
• NetBIOS Suffix format: username@DOMAIN

To verify that the SSSD PAM module is configured correctly, log on to the Linux VDA using a domain
user account that has not been used before.

1 sudo ssh localhost – l DOMAIN\\username

2
3 id -u
4 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the uid returned by the
command:

1 ls /tmp/krb5cc_{
2 uid }
3
4 <!--NeedCopy-->

Verify that the tickets in the user’s Kerberos credential cache are valid and not expired.

1 klist
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 55

Linux Virtual Delivery Agent 1912 LTSR

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

PBIS

Download the required PBIS package For example:

1 wget https://github.com/BeyondTrust/pbis-open/releases/download/8.8.0/
pbis-open-8.8.0.506.linux.x86_64.rpm.sh
2 <!--NeedCopy-->

Make the PBIS installation script executable For example:

1 chmod +x pbis-open-8.8.0.506.linux.x86_64.rpm.sh
2 <!--NeedCopy-->

Run the PBIS installation script For example:

1 sh pbis-open-8.8.0.506.linux.x86_64.rpm.sh
2 <!--NeedCopy-->

Join Windows domain Your domain controller must be reachable and you must have an Active Di‑
rectory user account with permissions to add computers to the domain:

1 /opt/pbis/bin/domainjoin-cli join domain-name user

2 <!--NeedCopy-->

The user is a domain user who has permissions to add computers to the Active Directory domain. The
domain‑name is the DNS name of the domain, for example, example.com.

Note: To set Bash as the default shell, run the /opt/pbis/bin/config LoginShellTemplate/bin/bash
command.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a PBIS‑joined Linux machine is
on the domain:

1 /opt/pbis/bin/domainjoin-cli query
2 <!--NeedCopy-->

If the machine is joined to a domain, this command returns the information about the currently joined
AD domain and OU. Otherwise, only the host name appears.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 56

Linux Virtual Delivery Agent 1912 LTSR

Verify user authentication To verify that PBIS can authenticate domain users through PAM, log on
to the Linux VDA using a domain user account that has not been used before.

1 ssh localhost -l domain\\user

2
3 id -u
4 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the UID returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

Step 4: Install .NET Core Runtime as a prerequisite

Before installing the Linux VDA, install .NET Core Runtime according to the instructions at https://do
cs.microsoft.com/en‑us/dotnet/core/install/linux‑package‑managers.

• For the 1912 LTSR initial release, CU1, and CU2, Install .NET Core Runtime 2.1.
• For CU3 and later releases, install .NET Core Runtime 3.1.

After installing .NET Core Runtime, run the which dotnet command to find your runtime path.

Based on the command output, set the .NET Core runtime binary path. For example, if the command
output is /aa/bb/dotnet, use /aa/bb as the .NET binary path.

Step 5: Download the Linux VDA package

Go to the Citrix Virtual Apps and Desktops download page. Expand the appropriate version of Citrix
Virtual Apps and Desktops and click Components to download the Linux VDA package that matches
your Linux distribution.

Step 6: Install the Linux VDA

You can do a fresh installation or upgrade an existing installation from the previous two versions and
from an LTSR release.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 57

Linux Virtual Delivery Agent 1912 LTSR

To do a fresh installation

1. (Optional) Uninstall the old version

If you installed an earlier version other than the previous two and an LTSR release, uninstall it
before installing the new version.

a) Stop the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx stop
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor
service daemon restarts the services you stopped.

b) Uninstall the package:

1 sudo rpm -e XenDesktopVDA

2 <!--NeedCopy-->

Note:

To run a command, the full path is needed; alternately, you can add /opt/Citrix/VDA/sbin
and /opt/Citrix/VDA/bin to the system path.

2. Install the Linux VDA

• Install the Linux VDA software using Yum:

For RHEL 7/CentOS 7:

1 sudo yum install -y XenDesktopVDA-19.12.0.50-1.el7_x.x86_64.

rpm
2 <!--NeedCopy-->

For RHEL 6/CentOS 6:

1 sudo yum install -y XenDesktopVDA-19.12.0.50-1.el6_x.x86_64.

rpm
2 <!--NeedCopy-->

• Install the Linux VDA software using the RPM package manager. Before doing so, you must
resolve the following dependencies:

For RHEL 7/CentOS 7:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 58

Linux Virtual Delivery Agent 1912 LTSR

1 sudo rpm -i XenDesktopVDA-19.12.0.50-1.el7_x.x86_64.rpm

2 <!--NeedCopy-->

For RHEL 6/CentOS 6:

1 sudo rpm -i XenDesktopVDA-19.12.0.50-1.el6_x.x86_64.rpm

2 <!--NeedCopy-->

RPM dependency list for RHEL 7/CentOS 7:

1 postgresql-server >= 9.2

2
3 postgresql-jdbc >= 9.2
4
5 java-1.8.0-openjdk >= 1.8.0
6
7 ImageMagick >= 6.7.8.9
8
9 firewalld >= 0.3.9
10
11 policycoreutils-python >= 2.0.83
12
13 dbus >= 1.6.12
14
15 dbus-x11 >= 1.6.12
16
17 xorg-x11-server-utils >= 7.7
18
19 xorg-x11-xinit >= 1.3.2
20
21 libXpm >= 3.5.10
22
23 libXrandr >= 1.4.1
24
25 libXtst >= 1.2.2
26
27 motif >= 2.3.4
28
29 pam >= 1.1.8
30
31 util-linux >= 2.23.2
32
33 bash >= 4.2
34
35 findutils >= 4.5
36
37 gawk >= 4.0
38
39 sed >= 4.2
40
41 cups >= 1.6.0
42
43 foomatic-filters >= 4.0.9

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 59

Linux Virtual Delivery Agent 1912 LTSR

44
45 openldap >= 2.4
46
47 cyrus-sasl >= 2.1
48
49 cyrus-sasl-gssapi >= 2.1
50
51 libxml2 >= 2.9
52
53 python-requests >= 2.6.0
54
55 gperftools-libs >= 2.4
56
57 rpmlib(FileDigests) <= 4.6.0-1
58
59 rpmlib(PayloadFilesHavePrefix) <= 4.0-1
60
61 pmlib(CompressedFileNames) <= 3.0.4-1
62
63 rpmlib(PayloadIsXz) <= 5.2-1
64 <!--NeedCopy-->

Note:

For a matrix of the Linux distributions and the Xorg versions that this version of the
Linux VDA supports, see System requirements.

RPM dependency list for RHEL 6/CentOS 6:

1 postgresql-jdbc >= 8.4

2
3 postgresql-server >= 8.4
4
5 java-1.8.0-openjdk >= 1.8.0
6
7 ImageMagick >= 6.5.4.7
8
9 GConf2 >= 2.28.0
10
11 system-config-firewall-base >= 1.2.27
12
13 policycoreutils-python >= 2.0.83
14
15 xorg-x11-server-utils >= 7.7
16
17 xorg-x11-xinit >= 1.0.9
18
19 ConsoleKit >= 0.4.1
20
21 dbus >= 1.2.24
22
23 dbus-x11 >= 1.2.24
24

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 60

Linux Virtual Delivery Agent 1912 LTSR

25 libXpm >= 3.5.10

26
27 libXrandr >= 1.4.1
28
29 libXtst >= 1.2.2
30
31 openmotif >= 2.3.3
32
33 pam >= 1.1.1
34
35 util-linux-ng >= 2.17.2
36
37 bash >= 4.1
38
39 findutils >= 4.4
40
41 gawk >= 3.1
42
43 sed >= 4.2
44
45 cups >= 1.4.0
46
47 foomatic >= 4.0.0
48
49 openldap >= 2.4
50
51 cyrus-sasl >= 2.1
52
53 cyrus-sasl-gssapi >= 2.1
54
55 libxml2 >= 2.7
56
57 python-requests >= 2.6.0
58
59 gperftools-libs >= 2.0
60
61 rpmlib(FileDigests) <= 4.6.0-1
62
63 rpmlib(PayloadFilesHavePrefix) <= 4.0-1
64
65 rpmlib(CompressedFileNames) <= 3.0.4-1
66
67 rpmlib(PayloadIsXz) <= 5.2-1
68 <!--NeedCopy-->

Note:

After installing the Linux VDA on RHEL 7.x, run the sudo yum install -y python-
websockify x11vnc command. The purpose is to install python-websockify and
x11vnc manually for using the session shadowing feature. For more information, see Shadow
sessions.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 61

Linux Virtual Delivery Agent 1912 LTSR

To upgrade an existing installation

You can upgrade an existing installation from the previous two versions and from an LTSR release.

• To upgrade your software using Yum:

For RHEL 7/CentOS 7:

1 sudo yum install -y XenDesktopVDA-19.12.0.50-1.el7_x.x86_64.rpm

2 <!--NeedCopy-->

For RHEL 6/CentOS 6:

1 sudo yum install -y XenDesktopVDA-19.12.0.50-1.el6_x.x86_64.rpm

2 <!--NeedCopy-->

• To upgrade your software using the RPM package manager:

For RHEL 7/CentOS 7:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.el7_x.x86_64.rpm

2 <!--NeedCopy-->

For RHEL 6/CentOS 6:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.el6_x.x86_64.rpm

2 <!--NeedCopy-->

Important:

Restart the Linux VDA machine after upgrading the software.

Step 7: Install NVIDIA GRID drivers

Enabling HDX 3D Pro requires you to install the NVIDIA GRID drivers on your hypervisor and on the VDA
machines.

To install and configure the NVIDIA GRID Virtual GPU Manager (the host driver) on the specific hyper‑
visors, see the following guides:

• Citrix Hypervisor
• VMware ESX

To install and configure the NVIDIA GRID guest VM drivers, perform the following steps:

1. Ensure that the guest VM is shut down.

2. In XenCenter, allocate a GPU to the VM.

3. Start the VM.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 62

Linux Virtual Delivery Agent 1912 LTSR

4. Prepare the VM for the NVIDIA GRID driver:

1 yum install gcc

2
3 yum install "kernel-devel-$(uname -r)"
4
5 systemctl set-default multi-user.target
6 <!--NeedCopy-->

5. Follow the steps in the Red Hat Enterprise Linux document to install the NVIDIA GRID driver.

Note:

During the GPU driver install, select the default (‘no’) for each question.

Important:

After GPU pass‑through is enabled, the Linux VM is no longer accessible through XenCenter. Use
SSH to connect.

Set the correct configuration for the card:

etc/X11/ctx-nvidia.sh

To take advantage of large resolutions and multi‑monitor capabilities, you need a valid NVIDIA license.
To apply for the license, follow the product documentation from “GRID Licensing Guide.pdf ‑ DU‑
07757‑001 September 2015.”

Step 8: Configure the Linux VDA

After installing the package, you must configure the Linux VDA by running the ctxsetup.sh script. Be‑
fore making any changes, the script verifies the environment and ensures that all dependencies are

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 63

Linux Virtual Delivery Agent 1912 LTSR

installed. If necessary, you can rerun the script at any time to change settings.

You can run the script manually with prompting, or automatically with preconfigured responses. Re‑
view Help about the script before proceeding:

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh --help

2 <!--NeedCopy-->

Prompted configuration

Run a manual configuration with prompted questions:

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh
2 <!--NeedCopy-->

Automated configuration

For an automated install, provide the options required by the setup script with environment variables.
If all required variables are present, the script does not prompt for any information.

Supported environment variables include:

• CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N –The Linux VDA supports specifying a Delivery

Controller name using a DNS CNAME record. Set to N by default.
• CTX_XDL_DDC_LIST=‘list‑ddc‑fqdns’–The Linux VDA requires a space‑separated list of Deliv‑
ery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Con‑
troller. At least one FQDN or CNAME alias must be specified.
• CTX_XDL_VDA_PORT=port‑number –The Linux VDA communicates with Delivery Controllers
through a TCP/IP port, which is port 80 by default.
• CTX_XDL_REGISTER_SERVICE=Y | N ‑ The Linux Virtual Desktop services are started after ma‑
chine startup. The value is set to Y by default.
• CTX_XDL_ADD_FIREWALL_RULES=Y | N –The Linux Virtual Desktop services require incoming
network connections to be allowed through the system firewall. You can automatically open the
required ports (ports 80 and 1494 by default) in the system firewall for the Linux Virtual Desktop.
Set to Y by default.
• CTX_XDL_AD_INTEGRATION=1 | 2 | 3 | 4 | 5 –The Linux VDA requires Kerberos configuration
settings to authenticate with the Delivery Controllers. The Kerberos configuration is determined
from the installed and configured Active Directory integration tool on the system. Specify the
supported Active Directory integration method to use:

– 1 –Samba Winbind
– 2 –Quest Authentication Services
– 3 –Centrify DirectControl

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 64

Linux Virtual Delivery Agent 1912 LTSR

– 4 –SSSD
– 5 –PBIS

• CTX_XDL_HDX_3D_PRO=Y | N –The Linux VDA supports HDX 3D Pro, a set of GPU acceleration
technologies designed to optimize the virtualization of rich graphics applications. If HDX
3D Pro is selected, the VDA is configured for VDI desktops (single‑session) mode –(that is,
CTX_XDL_VDI_MODE=Y).
• CTX_XDL_VDI_MODE=Y | N –Whether to configure the machine as a dedicated desktop delivery
model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set this
variable to Y. This variable is set to N by default.
• CTX_XDL_SITE_NAME=dns‑name –The Linux VDA discovers LDAP servers through DNS. To
limit the DNS search results to a local site, specify a DNS site name. This variable is set to
<none> by default.
• CTX_XDL_LDAP_LIST=‘list‑ldap‑servers’ –The Linux VDA queries DNS to discover LDAP
servers. If DNS cannot provide LDAP service records, you can provide a space‑separated list of
LDAP FQDNs with LDAP port. For example, ad1.mycompany.com:389. This variable is set to
<none> by default.
• CTX_XDL_SEARCH_BASE=search‑base‑set –The Linux VDA queries LDAP through a search
base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com). To
improve search performance, you can specify a search base (for example, OU=VDI,DC=mycompany,DC=com).
This variable is set to <none> by default.
• CTX_XDL_FAS_LIST=‘list‑fas‑servers’–The Federated Authentication Service (FAS) servers are
configured through AD Group Policy. Because the Linux VDA does not support AD Group Policy,
you can provide a semicolon‑separated list of FAS servers instead. The sequence must be the
same as configured in AD Group Policy. If any server address is removed, fill its blank with the
<none> text string and keep the sequence of server addresses without any changes.
• CTX_XDL_DOTNET_ RUNTIME_PATH=path‑to‑install‑dotnet‑runtime –The path to install
.NET Core Runtime for supporting the new broker agent service (ctxvda). The default path is
/usr/bin.
• CTX_XDL_START_SERVICE=Y | N –Whether or not the Linux VDA services are started when the
Linux VDA configuration is complete. Set to Y by default.

Set the environment variable and run the configure script:

1 export CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N
2
3 export CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’
4
5 export CTX_XDL_VDA_PORT=port-number
6
7 export CTX_XDL_REGISTER_SERVICE=Y|N
8
9 export CTX_XDL_ADD_FIREWALL_RULES=Y|N
10

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 65

Linux Virtual Delivery Agent 1912 LTSR

11 export CTX_XDL_AD_INTEGRATION=1|2|3|4|5
12
13 export CTX_XDL_HDX_3D_PRO=Y|N
14
15 export CTX_XDL_VDI_MODE=Y|N
16
17 export CTX_XDL_SITE_NAME=dns-site-name | '<none>'
18
19 export CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ | '<none>'
20
21 export CTX_XDL_SEARCH_BASE=search-base-set | '<none>'
22
23 export CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ | '<none>'
24
25 export CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime
26
27 export CTX_XDL_START_SERVICE=Y|N
28
29 sudo -E /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

When running the sudo command, type the ‑E option to pass the existing environment variables to
the new shell it creates. Citrix recommends that you create a shell script file from the preceding com‑
mands with #!/bin/bash as the first line.

Alternatively, you can specify all parameters by using a single command:

1 sudo CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N \
2
3 CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’ \
4
5 CTX_XDL_VDA_PORT=port-number \
6
7 CTX_XDL_REGISTER_SERVICE=Y|N \
8
9 CTX_XDL_ADD_FIREWALL_RULES=Y|N \
10
11 CTX_XDL_AD_INTEGRATION=1|2|3|4|5 \
12
13 CTX_XDL_HDX_3D_PRO=Y|N \
14
15 CTX_XDL_VDI_MODE=Y|N \
16
17 CTX_XDL_SITE_NAME=dns-name \
18
19 CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ \
20
21 CTX_XDL_SEARCH_BASE=search-base-set \
22
23 CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ \
24
25 CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime \
26

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 66

Linux Virtual Delivery Agent 1912 LTSR

27 CTX_XDL_START_SERVICE=Y|N \
28
29 /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

Remove configuration changes

In some scenarios, you might have to remove the configuration changes made by the ctxsetup.sh
script without uninstalling the Linux VDA package.

Review Help about this script before proceeding:

1 sudo /opt/Citrix/VDA/sbin/ctxcleanup.sh --help

2 <!--NeedCopy-->

To remove configuration changes:

1 sudo /opt/Citrix/VDA/sbin/ctxcleanup.sh
2 <!--NeedCopy-->

Important:

This script deletes all configuration data from the database and renders the Linux VDA inopera‑
ble.

Configuration logs

The ctxsetup.sh and ctxcleanup.sh scripts display errors on the console, with additional information
written to the configuration log file /tmp/xdl.configure.log.

Restart the Linux VDA services to have the changes take effect.

Step 9: Run XDPing

We provide a command‑line utility, the Linux XDPing tool, to check for common configuration is‑
sues with a Linux VDA environment. You can install the XDPing package on any machine running a
supported Linux distribution. XDPing does not require the Linux VDA package to be installed on the
machine. For more information about the tool, see Knowledge Center article CTX202015.

Step 10: Run the Linux VDA

After configuring the Linux VDA by using the ctxsetup.sh script, you can run the following commands
to control the Linux VDA.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 67

Linux Virtual Delivery Agent 1912 LTSR

Start the Linux VDA:

To start the Linux VDA services:

1 sudo /sbin/service ctxhdx start

2
3 sudo /sbin/service ctxvda start
4 <!--NeedCopy-->

Stop the Linux VDA:

To stop the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx stop
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor service daemon
restarts the services you stopped.

Restart the Linux VDA:

To restart the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx restart
4
5 sudo /sbin/service ctxvda start
6 <!--NeedCopy-->

Check the status of the Linux VDA:

To check the running status of the Linux VDA services:

1 sudo /sbin/service ctxvda status

2
3 sudo /sbin/service ctxhdx status
4 <!--NeedCopy-->

Step 11: Create the machine catalog in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating machine catalogs and adding Linux VDA machines is similar to the traditional
Windows VDA approach. For a more detailed description of how to complete these tasks, see Create
machine catalogs and Manage machine catalogs.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 68

Linux Virtual Delivery Agent 1912 LTSR

For creating machine catalogs that contain Linux VDA machines, there are a few restrictions that dif‑
ferentiate the process from creating machine catalogs for Windows VDA machines:

• For the operating system, select:

– The Multi‑session OS option for a hosted shared desktops delivery model.

– The Single‑session OS option for a VDI dedicated desktop delivery model.

• Do not mix Linux and Windows VDA machines in the same machine catalog.

Note:

Early versions of Citrix Studio did not support the notion of a “Linux OS.”However, selecting the
Windows Server OS or Server OS option implies an equivalent hosted shared desktops deliv‑
ery model. Selecting the Windows Desktop OS or Desktop OS option implies a single user per
machine delivery model.

Tip:

If you remove and rejoin a machine to the Active Directory domain, you must remove and add
the machine to the machine catalog again.

Step 12: Create the delivery group in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating a delivery group and adding machine catalogs containing Linux VDA ma‑
chines is almost identical to Windows VDA machines. For a more detailed description of how to com‑
plete these tasks, see Create Delivery Groups.

For creating delivery groups that contain Linux VDA machine catalogs, the following restrictions ap‑
ply:

• Ensure that the AD users and groups you select have been properly configured to log on to the
Linux VDA machines.
• Do not allow logon of unauthenticated (anonymous) users.
• Do not mix the delivery group with machine catalogs that contain Windows machines.

Important:

Publishing applications is supported with Linux VDA Version 1.4 and later. However, the Linux
VDA does not support the delivery of desktops and apps to the same machine.

For information about how to create machine catalogs and delivery groups, see Citrix Virtual Apps
and Desktops 7 1912 LTSR.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 69

Linux Virtual Delivery Agent 1912 LTSR

Install Linux Virtual Delivery Agent for SUSE manually

June 10, 2022

Important:

For fresh installations, we recommend you use easy install for a quick installation. Easy install
saves time and labor and is less error‑prone than the manual installation detailed in this article.

Step 1: Prepare for installation

Step 1a: Launch the YaST tool

The SUSE Linux Enterprise YaST tool is used for configuring all aspects of the operating system.

To launch the text‑based YaST tool:

1 su -
2
3 yast
4 <!--NeedCopy-->

Alternatively, launch the UI‑based YaST tool:

1 su -
2
3 yast2 &
4 <!--NeedCopy-->

Step 1b: Configure networking

The following sections provide information on configuring the various networking settings and ser‑
vices used by the Linux VDA. Configuring networking is carried out via the YaST tool, not via other
methods such as Network Manager. These instructions are based on using the UI‑based YaST tool.
The text‑based YaST tool can be used but has a different method of navigation that is not documented
here.

Configure host name and DNS

1. Open YaST Network Settings.

2. SLED 12 Only: On the Global Options tab, change the Network Setup Method to Wicked Ser‑
vice.
3. Open the Hostname/DNS tab.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 70

Linux Virtual Delivery Agent 1912 LTSR

4. Clear Change hostname via DHCP.

5. Check Assign Hostname to Loopback IP.
6. Edit the following to reflect your networking setup:

• Host name –Add the DNS host name of the machine.

• Domain name –Add the DNS domain name of the machine.
• Name server –Add the IP address of the DNS server. It is typically the IP address of the AD
Domain Controller.
• Domain search list –Add the DNS domain name.
Note:

The Linux VDA currently does not support NetBIOS name truncation. Therefore, the host name
must not exceed 15 characters.

Tip:

Use a–z, A–Z, 0–9, and hyphen (‑) characters only. Avoid underscores (_), spaces, and other sym‑
bols. Do not start a host name with a number and do not end with a hyphen. This rule also
applies to Delivery Controller host names.

Disable multicast DNS On SLED only, the default settings have multicast DNS (mDNS) enabled,
which can lead to inconsistent name resolution results. mDNS is not enabled on SLES by default, so
no action is required.

To disable mDNS, edit /etc/nsswitch.conf and change the line containing:

hosts: files mdns_minimal [NOTFOUND=return] dns

To:

hosts: files dns

Check the host name Verify that the host name is set correctly:

1 hostname
2 <!--NeedCopy-->

This command returns only the machine’s host name and not its fully qualified domain name
(FQDN).

Verify that the FQDN is set correctly:

1 hostname -f
2 <!--NeedCopy-->

This command returns the machine’s FQDN.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 71

Linux Virtual Delivery Agent 1912 LTSR

Check name resolution and service reachability Verify that you can resolve the FQDN and ping
the domain controller and Delivery Controller:

1 nslookup domain-controller-fqdn
2
3 ping domain-controller-fqdn
4
5 nslookup delivery-controller-fqdn
6
7 ping delivery-controller-fqdn
8 <!--NeedCopy-->

If you cannot resolve the FQDN or ping either of these machines, review the steps before proceed‑
ing.

Step 1c: Configure the NTP service

It is crucial to maintain accurate clock synchronization between the VDAs, Delivery Controllers, and
domain controllers. Hosting the Linux VDA as a virtual machine can cause clock skew problems. For
this reason, maintaining time using a remote NTP service is preferred. Some changes might be re‑
quired to the default NTP settings:

1. Open YaST NTP Configuration and select the General Settings tab.
2. In the Start NTP Daemon section, check Now and on Boot.
3. If present, select the Undisciplined Local Clock (LOCAL) item and click Delete.
4. Add an entry for an NTP server by clicking Add.
5. Select the Server Type and click Next.
6. Type the DNS name of the NTP server in the Address field. This service is normally hosted on
the Active Directory domain controller.
7. Leave the Options field unchanged.
8. Click Test to verify that the NTP service is reachable.
9. Click OK through the set of windows to save the changes.

Note:

For SLES 12 implementations, the NTP daemon might fail to start due to a known SUSE issue
with AppArmor policies. Follow the resolution for additional information.

Step 1d: Install Linux VDA dependent packages

The Linux VDA software for SUSE Linux Enterprise depends on the following packages:

• PostgreSQL

– SLED/SLES 12: Version 9.3 or later

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 72

Linux Virtual Delivery Agent 1912 LTSR

• OpenJDK 1.8.0
• Open Motif Runtime Environment 2.3.1 or later
• Cups

– SLED/SLES 12: Version 1.6.0 or later

• Foomatic filters

– SLED/SLES 12: Version 1.0.0 or later

• ImageMagick

– SLED/SLES 12: Version 6.8 or later

Add repositories Some required packages are not available in all SUSE Linux Enterprise reposito‑
ries:

• SLED 12: PostgreSQL is available for SLES 12 but not SLED 12. ImageMagick is available via the
SLE 12 SDK ISO or online repository.
• SLES 12: There are no issues. All packages are available. ImageMagick is available via the SLE
12 SDK ISO or online repository.

To resolve the issue, obtain missing packages from the media for the alternative edition of SLE from
which you are installing. That is, on SLED install missing packages from the SLES media, and on SLES
install missing packages from the SLED media. The following approach mounts both SLED and SLES
ISO media files and adds repositories.

• On SLED 12, run the commands:

1 sudo mkdir -p /mnt/sles

2
3 sudo mount -t iso9660 path-to-iso/SLES-12-SP3-DVD-x86_64-GM-DVD1.iso /
mnt/sles
4
5 sudo zypper ar -f /mnt/sles sles
6 <!--NeedCopy-->

• On SLED/SLES 12, run the commands:

1 sudo mkdir -p /mnt/sdk

2
3 sudo mount -t iso9660 path-to-iso/SLE-12-SP3-SDK-DVD-x86_64-GM-DVD1.iso
/mnt/sdk
4
5 sudo zypper ar -f /mnt/sdk sdk
6 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 73

Linux Virtual Delivery Agent 1912 LTSR

Install the Kerberos client Install the Kerberos client for mutual authentication between the Linux
VDA and the Delivery Controllers:

1 sudo zypper install krb5-client

2 <!--NeedCopy-->

The Kerberos client configuration depends on which Active Directory integration approach is used.
See the following description.

Install OpenJDK The Linux VDA depends on OpenJDK 1.8.0.

Tip:

To avoid registration failure with the Delivery Controller, ensure that you installed only OpenJDK
1.8.0. Remove all other versions of Java from your system.

• SLED:

1. On SLED, the Java runtime environment is typically installed with the operating system. Check
whether it has been installed:

1 sudo zypper info java-1_8_0-openjdk

2 <!--NeedCopy-->

2. Update to the latest version if the status is reported as out‑of‑date:

1 sudo zypper update java-1_8_0-openjdk

2 <!--NeedCopy-->

3. Check the Java version:

1 java -version
2 <!--NeedCopy-->

• SLES:

1. On SLES, install the Java runtime environment:

1 sudo zypper install java-1_8_0-openjdk

2 <!--NeedCopy-->

2. Check the Java version:

1 java -version
2 <!--NeedCopy-->

Install PostgreSQL On SLED/SLES 12, install the packages:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 74

Linux Virtual Delivery Agent 1912 LTSR

1 sudo zypper install postgresql-init

2
3 sudo zypper install postgresql-server
4
5 sudo zypper install postgresql-jdbc
6 <!--NeedCopy-->

Post‑installation steps are required to initialize the database service and to ensure that PostgreSQL is
started upon machine startup:

1 sudo systemctl enable postgresql

2
3 sudo systemctl restart postgresql
4 <!--NeedCopy-->

Database files locate at /var/lib/pgsql/data.

Remove repositories With dependent packages installed, the alternative edition repositories set
up earlier can now be removed and the media unmounted:

• on SLED 12, run the commands to remove the packages:

1 sudo zypper rr sles

2
3 sudo umount /mnt/sles
4
5 sudo rmdir /mnt/sles
6 <!--NeedCopy-->

• on SLED/SLES 12, run the commands to remove the packages:

1 sudo zypper rr sdk

2
3 sudo umount /mnt/sdk
4
5 sudo rmdir /mnt/sdk
6 <!--NeedCopy-->

Step 2: Prepare Linux VM for Hypervisor

Some changes are required when running the Linux VDA as a virtual machine on a supported hypervi‑
sor. Make the following changes according to the hypervisor platform in use. No changes are required
if you are running the Linux machine on bare metal hardware.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 75

Linux Virtual Delivery Agent 1912 LTSR

Fix time synchronization on Citrix Hypervisor

If the Citrix Hypervisor Time Sync feature is enabled, within each paravirtualized Linux VM you expe‑
rience issues with NTP and Citrix Hypervisor both trying to manage the system clock. To avoid the
clock becoming out of sync with other servers, synchronize the system clock within each Linux guest
with NTP. This case requires disabling host time synchronization. No changes are required in HVM
mode.

On some Linux distributions, if you are running a paravirtualized Linux kernel with Citrix VM Tools
installed, you can check whether the Citrix Hypervisor Time Sync feature is present and enabled from
within the Linux VM:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns 0 or 1:

• 0 ‑ The time sync feature is enabled, and must be disabled.

• 1 ‑ The time sync feature is disabled, and no further action is required.

If the /proc/sys/xen/independent_wallclock file is not present, the following steps are not
required.

If enabled, disable the time sync feature by writing 1 to the file:

1 sudo echo 1 > /proc/sys/xen/independent_wallclock

2 <!--NeedCopy-->

To make this change permanent and persistent after restart, edit the /etc/sysctl.conf file and add the
line:

xen.independent_wallclock = 1

To verify these changes, restart the system:

1 reboot
2 <!--NeedCopy-->

After restart, verify that the setting is correct:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns the value 1.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 76

Linux Virtual Delivery Agent 1912 LTSR

Fix time synchronization on Microsoft Hyper‑V

Linux VMs with Hyper‑V Linux Integration Services installed can apply the Hyper‑V time synchroniza‑
tion feature to use the host operating system’s time. To ensure that the system clock remains accurate,
enable this feature alongside the NTP services.

From the management operating system:

1. Open the Hyper‑V Manager console.

2. For the settings of a Linux VM, select Integration Services.
3. Ensure that Time synchronization is selected.

Note:

This approach is different from VMware and Citrix Hypervisor, where host time synchronization is
disabled to avoid conflicts with NTP. Hyper‑V time synchronization can coexist and supplement
NTP time synchronization.

Fix time synchronization on ESX and ESXi

If the VMware Time Synchronization feature is enabled, within each paravirtualized Linux VM you ex‑
perience issues with NTP and the hypervisor both trying to synchronize the system clock. To avoid
the clock becoming out of sync with other servers, the system clock within each Linux guest must be
synchronized with NTP. This case requires disabling host time synchronization.

If you are running a paravirtualized Linux kernel with VMware Tools installed:

1. Open the vSphere Client.

2. Edit settings for the Linux VM.
3. In the Virtual Machine Properties dialog, open the Options tab.
4. Select VMware Tools.
5. In the Advanced box, clear Synchronize guest time with host.

Step 3: Add the Linux virtual machine (VM) to the Windows domain

The Linux VDA supports several methods for adding Linux machines to the Active Directory (AD) do‑
main:

• Samba Winbind
• Quest Authentication Services
• Centrify DirectControl

Follow instructions based on your chosen method.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 77

Linux Virtual Delivery Agent 1912 LTSR

Note:

Session launches might fail when the same user name is used for the local account in the Linux
VDA and the account in AD.

Samba Winbind

Join Windows domain Your domain controller must be reachable and you must have an Active Di‑
rectory user account with permissions to add machines to the domain:

1. Open YaST Windows Domain Membership.

2. Make the following changes:

• Set the Domain or Workgroup to the name of your Active Directory domain or the IP ad‑
dress of the domain controller. Ensure that the domain name is in uppercase.
• Check Also Use SMB information for Linux Authentication.
• Check Create Home Directory on Login.
• Check Single Sign‑on for SSH.
• Ensure that Offline Authentication is not checked. This option is not compatible with the
Linux VDA.

3. Click OK. If prompted to install some packages, click Install.

4. If a domain controller is found, it asks whether you want to join the domain. Click Yes.

5. When prompted, type the credentials of a domain user with permission to add computers to
the domain and click OK.

6. A message indicating success is displayed.

7. If prompted to install some samba and krb5 packages, click Install.

YaST might have indicated that these changes require some services or the machine to be restarted.
We recommend you restart the machine:

1 su -
2
3 reboot
4 <!--NeedCopy-->

SLED/SLES 12 Only: Patch Kerberos credential cache name SLED/SLES 12 has changed the
default Kerberos credential cache name specification from the usual FILE:/tmp/krb5cc_%{uid} to
DIR:/run/user/%{uid}/krb5cc. This new DIR caching method is not compatible with the Linux VDA
and must be manually changed. As a root user, edit /etc/krb5.conf and add the following setting
under the [libdefaults] section if not set:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 78

Linux Virtual Delivery Agent 1912 LTSR

default_ccache_name = FILE:/tmp/krb5cc_%{ uid }

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory.

Run the net ads command of Samba to verify that the machine is joined to a domain:

1 sudo net ads testjoin

2 <!--NeedCopy-->

Run the following command to verify extra domain and computer object information:

1 sudo net ads info

2 <!--NeedCopy-->

Verify Kerberos configuration To ensure that Kerberos is configured correctly for use with the
Linux VDA, verify that the system keytab file has been created and contains valid keys:

1 sudo klist – ke
2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

1 sudo kinit -k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

Verify that the TGT ticket for the machine account has been cached using:

1 sudo klist
2 <!--NeedCopy-->

Examine the machine account details using:

1 sudo net ads status

2 <!--NeedCopy-->

Verify user authentication Use the wbinfo tool to verify that domain users can authenticate with
the domain:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 79

Linux Virtual Delivery Agent 1912 LTSR

1 wbinfo --krb5auth=domain\\username%password
2 <!--NeedCopy-->

The domain specified here is the AD domain name, not the Kerberos realm name. For the bash shell,
the backslash (\) character must be escaped with another backslash. This command returns a mes‑
sage indicating success or failure.

To verify that the Winbind PAM module is configured correctly, log on to the Linux VDA using a domain
user account that has not been used before.

1 ssh localhost -l domain\\username

2 id -u
3 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the uid returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Verify that the tickets in the user’s Kerberos credential cache are valid and not expired:

1 klist
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

A similar test can be performed by logging on to the Gnome or KDE console directly. Proceed to Step
6: Install the Linux VDA after the domain joining verification.

Quest Authentication Services

Configure Quest on domain controller Assume that you have installed and configured the Quest
software on the Active Directory domain controllers, and have been granted administrative privileges
to create computer objects in Active Directory.

Enable domain users to log on to Linux VDA machines To enable domain users to establish HDX
sessions on a Linux VDA machine:

1. In the Active Directory Users and Computers management console, open Active Directory user
properties for that user account.
2. Select the Unix Account tab.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 80

Linux Virtual Delivery Agent 1912 LTSR

3. Check Unix‑enabled.
4. Set the Primary GID Number to the group ID of an actual domain user group.

Note:

These instructions are equivalent for setting up domain users for logon using the console, RDP,
SSH, or any other remoting protocol.

Configure Quest on Linux VDA

Configure VAS daemon Auto‑renewal of Kerberos tickets must be enabled and disconnected. Au‑
thentication (offline logon) must be disabled:

1 sudo /opt/quest/bin/vastool configure vas vasd auto-ticket-renew-

interval 32400
2
3 sudo /opt/quest/bin/vastool configure vas vas_auth allow-disconnected-
auth false
4 <!--NeedCopy-->

This command sets the renewal interval to nine hours (32,400 seconds) which is one hour less than
the default 10‑hour ticket lifetime. Set this parameter to a lower value on systems with a shorter ticket
lifetime.

Configure PAM and NSS To enable domain user logon through HDX and other services such as su,
ssh, and RDP, run the following commands to manually configure PAM and NSS:

1 sudo /opt/quest/bin/vastool configure pam

2
3 sudo /opt/quest/bin/vastool configure nss
4 <!--NeedCopy-->

Join Windows domain Join the Linux machine to the Active Directory domain using the Quest
vastool command:

1 sudo /opt/quest/bin/vastool -u user join domain-name

2 <!--NeedCopy-->

The user is any domain user who has permissions to join computers to the Active Directory domain.
The domain‑name is the DNS name of the domain, for example, example.com.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a Quest‑joined Linux machine
is on the domain:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 81

Linux Virtual Delivery Agent 1912 LTSR

1 sudo /opt/quest/bin/vastool info domain

2 <!--NeedCopy-->

If the machine is joined to a domain, this command returns the domain name. If the machine is not
joined to any domain, the following error appears:

ERROR: No domain could be found.

ERROR: VAS_ERR_CONFIG: at ctx.c:414 in _ctx_init_default_realm
default_realm not configured in vas.conf. Computer may not be joined
to domain

Verify user authentication To verify that Quest can authenticate domain users through PAM, log
on to the Linux VDA using a domain user account that has not been used before.

1 ssh localhost -l domain\\username

2 id -u
3 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the uid returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Verify that the tickets in the Kerberos credential cache are valid and not expired:

1 /opt/quest/bin/vastool klist
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

A similar test can be performed by logging on to the Gnome or KDE console directly. Proceed to Step
6: Install the Linux VDA after the domain joining verification.

Centrify DirectControl

Join Windows domain With the Centrify DirectControl Agent installed, join the Linux machine to
the Active Directory domain using the Centrify adjoin command:

1 su –
2 adjoin -w -V -u user domain-name
3 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 82

Linux Virtual Delivery Agent 1912 LTSR

The user is any Active Directory domain user who has permissions to join computers to the Active
Directory domain. The domain‑name is the name of the domain to join the Linux machine to.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a Centrify‑joined Linux machine
is on the domain:

1 su –
2
3 adinfo
4 <!--NeedCopy-->

Verify that the Joined to domain value is valid and the CentrifyDC mode returns connected. If the
mode remains stuck in the starting state, then the Centrify client is experiencing server connection or
authentication problems.

More comprehensive system and diagnostic information is available using:

1 adinfo --sysinfo all

2
3 adinfo – diag
4 <!--NeedCopy-->

Test connectivity to the various Active Directory and Kerberos services.

1 adinfo --test
2 <!--NeedCopy-->

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

Step 4: Install .NET Core Runtime as a prerequisite

Before installing the Linux VDA, install .NET Core Runtime according to the instructions at https://do
cs.microsoft.com/en‑us/dotnet/core/install/linux‑package‑managers.

• For the 1912 LTSR initial release, CU1, and CU2, Install .NET Core Runtime 2.1.
• For CU3 and later releases, install .NET Core Runtime 3.1.

After installing .NET Core Runtime, run the which dotnet command to find your runtime path.

Based on the command output, set the .NET Core runtime binary path. For example, if the command
output is /aa/bb/dotnet, use /aa/bb as the .NET binary path.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 83

Linux Virtual Delivery Agent 1912 LTSR

Step 5: Download the Linux VDA package

Go to the Citrix Virtual Apps and Desktops download page. Expand the appropriate version of Citrix
Virtual Apps and Desktops and click Components to download the Linux VDA package that matches
your Linux distribution.

Step 6: Install the Linux VDA

Step 6a: Uninstall the old version

If you installed an earlier version other than the previous two and an LTSR release, uninstall it before
installing the new version.

1. Stop the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx stop
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor service
daemon restarts the services you stopped.

2. Uninstall the package:

1 sudo rpm -e XenDesktopVDA

2 <!--NeedCopy-->

Important:

Upgrading from the latest two versions is supported.

Note:

Installation components are located in /opt/Citrix/VDA/.

To run a command, the full path is needed; alternatively, you can add /opt/Citrix/VDA/sbin and
/opt/Citrix/VDA/bin to the system path.

Step 6b: Install the Linux VDA

Install the Linux VDA software using Zypper:

For SUSE 12:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 84

Linux Virtual Delivery Agent 1912 LTSR

1 sudo zypper install XenDesktopVDA-19.12.0.50-1.sle12_x.x86_64.rpm

2 <!--NeedCopy-->

Install the Linux VDA software using the RPM package manager. Before doing so, resolve the following
dependencies:

For SUSE 12:

1 sudo rpm -i XenDesktopVDA-19.12.0.50-1.sle12_x.x86_64.rpm

2 <!--NeedCopy-->

Step 6c: Upgrade the Linux VDA (optional)

You can upgrade an existing installation from the previous two versions and from an LTSR release.

For SUSE 12:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.sle12_x.x86_64.rpm

2 <!--NeedCopy-->

RPM Dependency list for SUSE 12:

1 postgresql-server >= 9.3

2
3 postgresql-jdbc >= 9.2
4
5 java-1.8.0-openjdk >= 1.8.0
6
7 ImageMagick >= 6.8
8
9 dbus-1 >= 1.8.8
10
11 dbus-1-x11 >= 1.8.8
12
13 libXpm4 >= 3.5.11
14
15 libXrandr2 >= 1.4.2
16
17 libXtst6 >= 1.2.2
18
19 motif >= 2.3
20
21 pam >= 1.1.8
22
23 bash >= 4.2
24
25 findutils >= 4.5
26
27 gawk >= 4.1
28
29 sed >= 4.2

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 85

Linux Virtual Delivery Agent 1912 LTSR

30
31 cups >= 1.6.0
32
33 cups-filters-foomatic-rip >= 1.0.0
34
35 openldap2 >= 2.4
36
37 cyrus-sasl >= 2.1
38
39 cyrus-sasl-gssapi >= 2.1
40
41 libxml2 >= 2.9
42
43 python-requests >= 2.8.1
44
45 rpmlib(PayloadFilesHavePrefix) <= 4.0-1
46
47 rpmlib(CompressedFileNames) <= 3.0.4-1
48
49 rpmlib(PayloadIsLzma) <= 4.4.6-1
50
51 libtcmalloc4 >= 2.5
52
53 libcap-progs >= 2.22
54
55 xorg-x11-server >= 7.6_1.18.3-76.15
56
57 ibus >= 1.5
58 <!--NeedCopy-->

Important:

Restart the Linux VDA machine after upgrading.

Step 7: Install NVIDIA GRID drivers

Enabling HDX 3D Pro requires you to install the NVIDIA GRID drivers on your hypervisor and on the VDA
machines.

To install and configure the NVIDIA GRID Virtual GPU Manager (the host driver) on the specific hyper‑
visors, see the following guides:

• Citrix Hypervisor
• VMware ESX

To install and configure the NVIDIA GRID guest VM drivers, perform the following general steps:

1. Ensure that the guest VM is shut down.

2. In the hypervisor control panel, allocate a GPU to the VM.
3. Start the VM.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 86

Linux Virtual Delivery Agent 1912 LTSR

4. Install the guest VM driver on the VM.

Step 8: Configure the Linux VDA

After installing the package, you must configure the Linux VDA by running the ctxsetup.sh script. Be‑
fore making any changes, the script verifies the environment and ensures that all dependencies are
installed. If necessary, you can rerun the script at any time to change settings.

You can run the script manually with prompting, or automatically with preconfigured responses. Re‑
view Help about the script before proceeding:

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh – help

2 <!--NeedCopy-->

Prompted configuration

Run a manual configuration with prompted questions:

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh
2 <!--NeedCopy-->

Automated configuration

For an automated installation, provide the options required by the setup script with environment vari‑
ables. If all required variables are present, the script does not prompt for any information.

Supported environment variables include:

• CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N –The Linux VDA supports specifying a Delivery

Controller name using a DNS CNAME record. Set to N by default.
• CTX_XDL_DDC_LIST=‘list‑ddc‑fqdns’–The Linux VDA requires a space‑separated list of Deliv‑
ery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Con‑
troller. At least one FQDN or CNAME alias must be specified.
• CTX_XDL_VDA_PORT=port‑number –The Linux VDA communicates with Delivery Controllers
through a TCP/IP port, which is port 80 by default.
• CTX_XDL_REGISTER_SERVICE=Y | N ‑ The Linux Virtual Desktop services are started after ma‑
chine startup. The value is set to Y by default.
• CTX_XDL_ADD_FIREWALL_RULES=Y | N –The Linux Virtual Desktop services require incoming
network connections to be allowed through the system firewall. You can automatically open the
required ports (ports 80 and 1494 by default) in the system firewall for the Linux Virtual Desktop.
Set to Y by default.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 87

Linux Virtual Delivery Agent 1912 LTSR

• CTX_XDL_AD_INTEGRATION=1 | 2 | 3 | 4 –The Linux VDA requires Kerberos configuration set‑

tings to authenticate with the Delivery Controllers. The Kerberos configuration is determined
from the installed and configured Active Directory integration tool on the system. Specify the
supported Active Directory integration method to use:

– 1 –Samba Winbind
– 2 –Quest Authentication Services
– 3 –Centrify DirectControl
– 4 –SSSD

• CTX_XDL_HDX_3D_PRO=Y | N –The Linux VDA supports HDX 3D Pro, a set of GPU acceleration
technologies designed to optimize the virtualization of rich graphics applications. If HDX
3D Pro is selected, the VDA is configured for VDI desktops (single‑session) mode –(that is,
CTX_XDL_VDI_MODE=Y).
• CTX_XDL_VDI_MODE=Y | N –Whether to configure the machine as a dedicated desktop delivery
model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set this
variable to Y. This variable is set to N by default.
• CTX_XDL_SITE_NAME=dns‑name –The Linux VDA discovers LDAP servers through DNS. To
limit the DNS search results to a local site, specify a DNS site name. This variable is set to
<none> by default.
• CTX_XDL_LDAP_LIST=‘list‑ldap‑servers’ –The Linux VDA queries DNS to discover LDAP
servers. If DNS cannot provide LDAP service records, you can provide a space‑separated list of
LDAP FQDNs with LDAP port. For example, ad1.mycompany.com:389. This variable is set to
<none> by default.
• CTX_XDL_SEARCH_BASE=search‑base‑set –The Linux VDA queries LDAP through a search
base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com). To
improve search performance, you can specify a search base (for example, OU=VDI,DC=mycompany,DC=com).
This variable is set to <none> by default.
• CTX_XDL_FAS_LIST=‘list‑fas‑servers’–The Federated Authentication Service (FAS) servers are
configured through AD Group Policy. Because the Linux VDA does not support AD Group Policy,
you can provide a semicolon‑separated list of FAS servers instead. The sequence must be the
same as configured in AD Group Policy. If any server address is removed, fill its blank with the
<none> text string and keep the sequence of server addresses without any changes.
• CTX_XDL_DOTNET_ RUNTIME_PATH=path‑to‑install‑dotnet‑runtime –The path to install
.NET Core Runtime for supporting the new broker agent service (ctxvda). The default path is
/usr/bin.
• CTX_XDL_START_SERVICE=Y | N –Whether or not the Linux VDA services are started when the
Linux VDA configuration is complete. Set to Y by default.

Set the environment variable and run the configure script:

1 export CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 88

Linux Virtual Delivery Agent 1912 LTSR

2
3 export CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’
4
5 export CTX_XDL_VDA_PORT=port-number
6
7 export CTX_XDL_REGISTER_SERVICE=Y|N
8
9 export CTX_XDL_ADD_FIREWALL_RULES=Y|N
10
11 export CTX_XDL_AD_INTEGRATION=1|2|3|4
12
13 export CTX_XDL_HDX_3D_PRO=Y|N
14
15 export CTX_XDL_VDI_MODE=Y|N
16
17 export CTX_XDL_SITE_NAME=dns-site-name | '<none>'
18
19 export CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ | '<none>'
20
21 export CTX_XDL_SEARCH_BASE=search-base-set | '<none>'
22
23 export CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ | '<none>'
24
25 export CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime
26
27 export CTX_XDL_START_SERVICE=Y|N
28
29 sudo -E /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

When running the sudo command, type the ‑E option to pass the existing environment variables to the
new shell it creates. We recommend that you create a shell script file from the preceding commands
with #!/bin/bash as the first line.

Alternatively, you can specify all parameters by using a single command:

1 sudo CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N \
2
3 CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’ \
4
5 CTX_XDL_VDA_PORT=port-number \
6
7 CTX_XDL_REGISTER_SERVICE=Y|N \
8
9 CTX_XDL_ADD_FIREWALL_RULES=Y|N \
10
11 CTX_XDL_AD_INTEGRATION=1|2|3|4 \
12
13 CTX_XDL_HDX_3D_PRO=Y|N \
14
15 CTX_XDL_VDI_MODE=Y|N \
16
17 CTX_XDL_SITE_NAME=dns-name \

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 89

Linux Virtual Delivery Agent 1912 LTSR

18
19 CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ \
20
21 CTX_XDL_SEARCH_BASE=search-base-set \
22
23 CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ \
24
25 CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime \
26
27 CTX_XDL_START_SERVICE=Y|N \
28
29 /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

Remove configuration changes

In some scenarios, you might have to remove the configuration changes made by the ctxsetup.sh
script without uninstalling the Linux VDA package.

Review Help about this script before proceeding:

1 sudo /usr/local/sbin/ctxcleanup.sh --help

2 <!--NeedCopy-->

To remove configuration changes:

1 sudo /usr/local/sbin/ctxcleanup.sh
2 <!--NeedCopy-->

Important:

This script deletes all configuration data from the database and renders the Linux VDA inopera‑
ble.

Configuration logs

The ctxsetup.sh and ctxcleanup.sh scripts display errors on the console, with additional information
written to a configuration log file:

/tmp/xdl.configure.log

Restart the Linux VDA services to have the changes take effect.

Step 9: Run XDPing

We provide a command‑line utility, the Linux XDPing tool, to check for common configuration is‑
sues with a Linux VDA environment. You can install the XDPing package on any machine running a

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 90

Linux Virtual Delivery Agent 1912 LTSR

supported Linux distribution. XDPing does not require the Linux VDA package to be installed on the
machine. For more information about the tool, see Knowledge Center article CTX202015.

Step 10: Run the Linux VDA

After configuring the Linux VDA by using the ctxsetup.sh script, you can run the following commands
to control the Linux VDA.
Start the Linux VDA:
To start the Linux VDA services:

1 sudo /sbin/service ctxhdx start

2
3 sudo /sbin/service ctxvda start
4 <!--NeedCopy-->

Stop the Linux VDA:

To stop the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx stop
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor service daemon
restarts the services you stopped.

Restart the Linux VDA:

To restart the Linux VDA services:

1 sudo /sbin/service ctxvda stop

2
3 sudo /sbin/service ctxhdx restart
4
5 sudo /sbin/service ctxvda start
6 <!--NeedCopy-->

Check the Linux VDA status:

To check the running status of the Linux VDA services:

1 sudo /sbin/service ctxvda status

2
3 sudo /sbin/service ctxhdx status
4 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 91

Linux Virtual Delivery Agent 1912 LTSR

Step 11: Create the machine catalog in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating machine catalogs and adding Linux VDA machines is similar to the traditional
Windows VDA approach. For a more detailed description of how to complete these tasks, see Create
machine catalogs and Manage machine catalogs.

For creating machine catalogs that contain Linux VDA machines, there are a few restrictions that dif‑
ferentiate the process from creating machine catalogs for Windows VDA machines:

• For the operating system, select:

– The Multi‑session OS option for a hosted shared desktops delivery model.

– The Single‑session OS option for a VDI dedicated desktop delivery model.

• Do not mix Linux and Windows VDA machines in the same machine catalog.

Note:

Early versions of Citrix Studio did not support the notion of a “Linux OS.”However, selecting the
Windows Server OS or Server OS option implies an equivalent hosted shared desktops deliv‑
ery model. Selecting the Windows Desktop OS or Desktop OS option implies a single user per
machine delivery model.

Tip:

If you remove and rejoin a machine to the Active Directory domain, you must remove and add
the machine to the machine catalog again.

Step 12: Create the delivery group in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating a delivery group and adding machine catalogs containing Linux VDA ma‑
chines is almost identical to Windows VDA machines. For a more detailed description of how to com‑
plete these tasks, see Create Delivery Groups.

For creating delivery groups that contain Linux VDA machine catalogs, the following restrictions ap‑
ply:

• Ensure that the AD users and groups you select have been properly configured to log on to the
Linux VDA machines.
• Do not allow logon of unauthenticated (anonymous) users.
• Do not mix the delivery group with machine catalogs that contain Windows machines.

Important:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 92

Linux Virtual Delivery Agent 1912 LTSR

Publishing applications is supported with Linux VDA Version 1.4 and later. However, the Linux
VDA does not support the delivery of desktops and apps to the same machine.

For information about how to create machine catalogs and delivery groups, see Citrix Virtual Apps
and Desktops 7 1912 LTSR.

Install Linux Virtual Delivery Agent for Ubuntu manually

June 10, 2022

Important:

For fresh installations, we recommend you use easy install for a quick installation. Easy install
saves time and labor and is less error‑prone than the manual installation detailed in this article.

Step 1: Prepare Ubuntu for VDA installation

Step 1a: Verify the network configuration

Ensure that the network is connected and configured correctly. For example, you must configure the
DNS server on the Linux VDA.

If you are using a Ubuntu 18.04 Live Server, make the following change in the /etc/cloud/cloud.cfg
configuration file before setting the host name:

preserve_hostname: true

Step 1b: Set the host name

To ensure that the host name of the machine is reported correctly, change the /etc/hostname file to
contain only the host name of the machine.

hostname

Step 1c: Assign a loopback address to the host name

Ensure that the DNS domain name and Fully Qualified Domain Name (FQDN) of the machine are re‑
ported back correctly. The way is to change the following line of the /etc/hosts file to include the
FQDN and host name as the first two entries:

127.0.0.1 hostname-fqdn hostname localhost

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 93

Linux Virtual Delivery Agent 1912 LTSR

For example:
127.0.0.1 vda01.example.com vda01 localhost
Remove any other references to hostname‑fqdn or hostname from other entries in the file.
Note:

The Linux VDA currently does not support NetBIOS name truncation. Therefore, the host name
must not exceed 15 characters.

Tip:

Use a–z, A–Z, 0–9, and hyphen (‑) characters only. Avoid underscores (_), spaces, and other sym‑
bols. Do not start a host name with a number and do not end with a hyphen. This rule also
applies to Delivery Controller host names.

Step 1d: Check the host name

Verify that the host name is set correctly:

1 hostname
2 <!--NeedCopy-->

This command returns only the host name of the machine and not its FQDN.
Verify that the FQDN is set correctly:

1 hostname -f
2 <!--NeedCopy-->

This command returns the FQDN of the machine.

Step 1e: Disable multicast DNS

The default settings have multicast DNS (mDNS) enabled, which can lead to inconsistent name reso‑
lution results.
To disable mDNS, edit /etc/nsswitch.conf and change the line containing:
hosts: files mdns_minimal [NOTFOUND=return] dns
To:
hosts: files dns

Step 1f: Check name resolution and service reachability

Verify that you can resolve the FQDN and ping the domain controller and Delivery Controller:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 94

Linux Virtual Delivery Agent 1912 LTSR

1 nslookup domain-controller-fqdn
2
3 ping domain-controller-fqdn
4
5 nslookup delivery-controller-fqdn
6
7 ping delivery-controller-fqdn
8 <!--NeedCopy-->

If you cannot resolve the FQDN or ping either of these machines, review the steps before proceed‑
ing.

Step 1g: Configure clock synchronization (chrony)

Maintaining accurate clock synchronization between the VDAs, Delivery Controllers and domain con‑
trollers is crucial. Hosting the Linux VDA as a virtual machine can cause clock skew problems. For this
reason, synchronizing time with a remote time service is preferred.

Install chrony:

1 apt-get install chrony

2 <!--NeedCopy-->

As a root user, edit /etc/chrony/chrony.conf and add a server entry for each remote time server:

server peer1-fqdn-or-ip-address iburst

server peer2-fqdn-or-ip-address iburst

In a typical deployment, synchronize time from the local domain controllers and not directly from pub‑
lic NTP pool servers. Add a server entry for each Active Directory domain controller in the domain.

Remove any other server or pool entries listed including loopback IP address, localhost, and public
server *.pool.ntp.org entries.

Save changes and restart the Chrony daemon:

1 sudo systemctl restart chrony

2 <!--NeedCopy-->

Step 1h: Install OpenJDK

The Linux VDA depends on OpenJDK. Typically, the runtime environment is installed as part of the
operating system installation.

On Ubuntu 16.04, install OpenJDK by using:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 95

Linux Virtual Delivery Agent 1912 LTSR

1 sudo apt-get install -y default-jdk

2 <!--NeedCopy-->

On Ubuntu 18.04, install OpenJDK by using:

1 sudo apt-get install -y openjdk-8-jdk

2 <!--NeedCopy-->

Step 1i: Install PostgreSQL

The Linux VDA requires PostgreSQL Version 9.x on Ubuntu:

1 sudo apt-get install -y postgresql

2
3 sudo apt-get install -y libpostgresql-jdbc-java
4 <!--NeedCopy-->

Step 1j: Install Motif

1 sudo apt-get install -y libxm4

2 <!--NeedCopy-->

Step 1k: Install other packages

1 sudo apt-get install -y libsasl2-2

2
3 sudo apt-get install -y libsasl2-modules-gssapi-mit
4
5 sudo apt-get install -y libldap-2.4-2
6
7 sudo apt-get install -y krb5-user
8
9 sudo apt-get install -y cups
10 <!--NeedCopy-->

Step 1l: Install the following package (Ubuntu 18.04 only)

1 sudo apt-get install -y libgtk2.0-0

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 96

Linux Virtual Delivery Agent 1912 LTSR

Step 2: Prepare the hypervisor

Some changes are required when running the Linux VDA as a virtual machine on a supported hypervi‑
sor. Make the following changes according to the hypervisor platform in use. No changes are required
if you are running the Linux machine on bare metal hardware.

Fix time synchronization on Citrix Hypervisor

When the Citrix Hypervisor Time Sync feature is enabled, within each paravirtualized Linux VM you
experience issues with NTP and Citrix Hypervisor, both of which try to manage the system clock. To
avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization. No
changes are required in HVM mode.

On some Linux distributions, if you are running a paravirtualized Linux kernel with Citrix VM Tools
installed, you can check whether the Citrix Hypervisor Time Sync feature is present and enabled from
within the Linux VM:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns 0 or 1:

• 0 ‑ The time sync feature is enabled, and must be disabled.

• 1 ‑ The time sync feature is disabled, and no further action is required.

If the /proc/sys/xen/independent_wallclock file is not present, the following steps are not required.

If enabled, disable the time sync feature by writing 1 to the file:

1 sudo echo 1 > /proc/sys/xen/independent_wallclock

2 <!--NeedCopy-->

To make this change permanent and persistent after restart, edit the /etc/sysctl.conf file and add the
line:

xen.independent_wallclock = 1

To verify these changes, restart the system:

1 su -
2
3 cat /proc/sys/xen/independent_wallclock
4 <!--NeedCopy-->

This command returns the value 1.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 97

Linux Virtual Delivery Agent 1912 LTSR

Fix time synchronization on Microsoft Hyper‑V

Linux VMs with Hyper‑V Linux Integration Services installed can use the Hyper‑V time synchronization
feature to use the host operating system’s time. To ensure that the system clock remains accurate,
you must enable this feature alongside NTP services.

From the management operating system:

1. Open the Hyper‑V Manager console.

2. For the settings of a Linux VM, select Integration Services.
3. Ensure that Time synchronization is selected.

Note:

This approach is different from VMware and Citrix Hypervisor, where host time synchronization is
disabled to avoid conflicts with NTP. Hyper‑V time synchronization can coexist and supplement
NTP time synchronization.

Fix time synchronization on ESX and ESXi

When the VMware Time Synchronization feature is enabled, within each paravirtualized Linux VM you
experience issues with the NTP and the hypervisor, both of which try to synchronize the system clock.
To avoid the clock becoming out of sync with other servers, ensure that the system clock within each
Linux guest is synchronized with the NTP. This case requires disabling host time synchronization.

If you are running a paravirtualized Linux kernel with VMware Tools installed:

1. Open the vSphere Client.

2. Edit settings for the Linux VM.
3. In the Virtual Machine Properties dialog, open the Options tab.
4. Select VMware Tools.
5. In the Advanced box, clear Synchronize guest time with host.

Step 3: Add the Linux virtual machine (VM) to the Windows domain

The Linux VDA supports several methods for adding Linux machines to the Active Directory (AD) do‑
main:

• Samba Winbind
• Quest Authentication Services
• Centrify DirectControl
• SSSD
• PBIS

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 98

Linux Virtual Delivery Agent 1912 LTSR

Follow instructions based on your chosen method.

Note:

Session launches might fail when the same user name is used for the local account in the Linux
VDA and the account in AD.

Samba Winbind

Install or update the required packages

1 sudo apt-get install winbind samba libnss-winbind libpam-winbind krb5-
config krb5-locales krb5-user
2 <!--NeedCopy-->

Enable Winbind daemon to start on machine startup The Winbind daemon must be configured
to start on machine startup:

1 sudo systemctl enable winbind

2 <!--NeedCopy-->

Configure Kerberos Open /etc/krb5.conf as a root user, and make the following settings:

1 [libdefaults]
2
3 default_realm = REALM
4
5 dns_lookup_kdc = false
6
7
8
9 [realms]
10
11 REALM = {
12
13
14 admin_server = domain-controller-fqdn
15
16 kdc = domain-controller-fqdn
17
18 }
19
20
21
22
23 [domain_realm]
24
25 domain-dns-name = REALM
26
27 .domain-dns-name = REALM

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 99

Linux Virtual Delivery Agent 1912 LTSR

28 <!--NeedCopy-->

The domain‑dns‑name property in this context is the DNS domain name, such as example.com. The
REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM.

Configure Winbind Authentication Configure Winbind manually because Ubuntu does not have a
tool like authconfig in RHEL and yast2 in SUSE.

Open /etc/samba/smb.conf, and make the following settings:

1 [global]
2
3 workgroup = WORKGROUP
4
5 security = ADS
6
7 realm = REALM
8
9 encrypt passwords = yes
10
11 idmap config *:range = 16777216-33554431
12
13 winbind trusted domains only = no
14
15 kerberos method = secrets and keytab
16
17 winbind refresh tickets = yes
18
19 template shell = /bin/bash
20 <!--NeedCopy-->

WORKGROUP is the first field in REALM, and REALM is the Kerberos realm name in uppercase.

Configure nsswitch Open /etc/nsswitch.conf, and append winbind to the following lines:

passwd: compat winbind

group: compat winbind

Join Windows Domain Your domain controller must be reachable and you must have an Active
Directory user account with permissions to add computers to the domain:

1 sudo net ads join REALM -U user

2 <!--NeedCopy-->

Where REALM is the Kerberos realm name in uppercase, and user is a domain user with permissions
to add computers to the domain.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 100

Linux Virtual Delivery Agent 1912 LTSR

Restart winbind
1 sudo systemctl restart winbind
2 <!--NeedCopy-->

Configure PAM for Winbind Run the following command and ensure that the Winbind NT/Active
Directory authentication and Create home directory on login options are selected:

1 sudo pam-auth-update
2 <!--NeedCopy-->

Tip:

The winbind daemon stays running only if the machine is joined to a domain.

Verify Domain Membership The Delivery Controller requires that all VDA machines, whether Win‑
dows or Linux, have a computer object in Active Directory.

Run the net ads command of Samba to verify that the machine is joined to a domain:

1 sudo net ads testjoin

2 <!--NeedCopy-->

Run the following command to verify extra domain and computer object information:

1 sudo net ads info

2 <!--NeedCopy-->

Verify Kerberos Configuration To verify that Kerberos is configured correctly for use with the Linux
VDA, verify that the system keytab file has been created and contains valid keys:

1 sudo klist -ke

2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

1 sudo kinit -k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

Verify that the TGT ticket for the machine account has been cached using:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 101

Linux Virtual Delivery Agent 1912 LTSR

1 sudo klist
2 <!--NeedCopy-->

Examine the account details of the machine using:

1 sudo net ads status

2 <!--NeedCopy-->

Verify user authentication Use the wbinfo tool to verify that domain users can authenticate with
the domain:

1 wbinfo --krb5auth=domain\\username%password
2 <!--NeedCopy-->

The domain specified here is the AD domain name, not the Kerberos realm name. For the bash shell,
the backslash (\) character must be escaped with another backslash. This command returns a mes‑
sage indicating success or failure.

To verify that the Winbind PAM module is configured correctly, log on to the Linux VDA using a domain
user account that has not been used before.

1 ssh localhost -l domain\\username

2
3 id -u
4 <!--NeedCopy-->

Note:

To run an SSH command successfully, ensure that SSH is enabled and working properly.

Verify that a corresponding Kerberos credential cache file was created for the uid returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Verify that the tickets in the user’s Kerberos credential cache are valid and not expired:

1 klist
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

A similar test can be performed by logging on to the Gnome or KDE console directly. Proceed to Step
6: Install the Linux VDA after the domain joining verification.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 102

Linux Virtual Delivery Agent 1912 LTSR

Tip:

If you succeed in user authentication but cannot show your desktop when logging on with a do‑
main account, restart the machine and then try again.

Quest Authentication Services

Configure Quest on domain controller Assume that you have installed and configured the Quest
software on the Active Directory domain controllers, and have been granted administrative privileges
to create computer objects in Active Directory.

Enable domain users to log on to Linux VDA machines To enable domain users to establish HDX
sessions on a Linux VDA machine:

1. In the Active Directory Users and Computers management console, open Active Directory user
properties for that user account.
2. Select the Unix Account tab.
3. Check Unix‑enabled.
4. Set the Primary GID Number to the group ID of an actual domain user group.

Note:

These instructions are equivalent for setting up domain users for logon using the console, RDP,
SSH, or any other remoting protocol.

Configure Quest on Linux VDA

Work around SELinux policy enforcement The default RHEL environment has SELinux fully en‑
forced. This enforcement interferes with the Unix domain socket IPC mechanisms used by Quest, and
prevents domain users from logging on.

The convenient way to work around this issue is to disable SELinux. As a root user, edit /etc/selinux/‑
config and change the SELinux setting:

SELINUX=disabled

This change requires a machine restart:

1 reboot
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 103

Linux Virtual Delivery Agent 1912 LTSR

Important:

Use this setting carefully. Reenabling SELinux policy enforcement after disabling can cause a
complete lockout, even for the root user and other local users.

Configure VAS daemon Auto‑renewal of Kerberos tickets must be enabled and disconnected. Au‑
thentication (offline logon) must be disabled:

1 sudo /opt/quest/bin/vastool configure vas vasd auto-ticket-renew-

interval 32400
2
3 sudo /opt/quest/bin/vastool configure vas vas_auth allow-disconnected-
auth false
4 <!--NeedCopy-->

This command sets the renewal interval to nine hours (32,400 seconds) which is one hour less than
the default 10‑hour ticket lifetime. Set this parameter to a lower value on systems with a shorter ticket
lifetime.

Configure PAM and NSS To enable domain user logon through HDX and other services such as su,
ssh, and RDP, run the following commands to manually configure PAM and NSS:

1 sudo /opt/quest/bin/vastool configure pam

2
3 sudo /opt/quest/bin/vastool configure nss
4 <!--NeedCopy-->

Join Windows domain Join the Linux machine to the Active Directory domain using the Quest
vastool command:

1 sudo /opt/quest/bin/vastool -u user join domain-name

2 <!--NeedCopy-->

The user is any domain user with permissions to join computers to the Active Directory domain. The
domain‑name is the DNS name of the domain, for example, example.com.

Verify domain membership The Delivery Controller requires that all VDA machines, whether Win‑
dows or Linux, have a computer object in Active Directory. To verify that a Quest‑joined Linux machine
is on the domain:

1 sudo /opt/quest/bin/vastool info domain

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 104

Linux Virtual Delivery Agent 1912 LTSR

If the machine is joined to a domain, this command returns the domain name. If the machine is not
joined to any domain, the following error appears:

ERROR: No domain could be found.

ERROR: VAS_ERR_CONFIG: at ctx.c:414 in _ctx_init_default_realm
default_realm not configured in vas.conf. Computer may not be joined
to domain

Verify user authentication To verify that Quest can authenticate domain users through PAM, log
on to the Linux VDA using a domain user account that has not been used before.

1 ssh localhost -l domain\\username

2
3 id -u
4 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the UID returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Verify that the tickets in the Kerberos credential cache are valid and not expired:

1 /opt/quest/bin/vastool klist
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

Centrify DirectControl

Join Windows domain With the Centrify DirectControl Agent installed, join the Linux machine to
the Active Directory domain using the Centrify adjoin command:

1 su –
2 adjoin -w -V -u user domain-name
3 <!--NeedCopy-->

The user parameter is any Active Directory domain user with permissions to join computers to the
Active Directory domain. The domain‑name parameter is the name of the domain to join the Linux
machine to.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 105

Linux Virtual Delivery Agent 1912 LTSR

Verify domain membership The Delivery Controller requires that all VDA machines, whether Win‑
dows or Linux, have a computer object in Active Directory. To verify that a Centrify‑joined Linux ma‑
chine is on the domain:

1 su –
2
3 adinfo
4 <!--NeedCopy-->

Verify that the Joined to domain value is valid and the CentrifyDC mode returns connected. If the
mode remains stuck in the starting state, then the Centrify client is experiencing server connection or
authentication problems.

More comprehensive system and diagnostic information is available using:

1 adinfo --sysinfo all

2
3 adinfo --diag
4 <!--NeedCopy-->

To test connectivity to the various Active Directory and Kerberos services:

1 adinfo --test
2 <!--NeedCopy-->

SSSD

Configure Kerberos Run the following command to install Kerberos:

1 sudo apt-get install krb5-user

2 <!--NeedCopy-->

To configure Kerberos, open /etc/krb5.conf as root and make the following settings:

1 [libdefaults]
2
3 default_realm = REALM
4
5 dns_lookup_kdc = false
6
7 [realms]
8
9 REALM = {
10
11
12 admin_server = domain-controller-fqdn
13
14 kdc = domain-controller-fqdn
15
16 }

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 106

Linux Virtual Delivery Agent 1912 LTSR

17
18
19 [domain_realm]
20
21 domain-dns-name = REALM
22
23 .domain-dns-name = REALM
24 <!--NeedCopy-->

The domain-dns-name property in this context is the DNS domain name, such as example.com.
The REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM.

Join the domain SSSD must be configured to use Active Directory as its identity provider and Ker‑
beros for authentication. However, SSSD does not provide AD client functions for joining the domain
and managing the system keytab file. You can use adcli, realmd, or Samba instead.

Note:

This section only provides information for adcli and Samba.

• If you use adcli to join the domain, complete the following steps:

1. Install adcli.

1 sudo apt-get install adcli

2 <!--NeedCopy-->

2. Join the domain with adcli.

Remove the old system keytab file and join the domain using:

1 su -
2
3 rm -rf /etc/krb5.keytab
4
5 adcli join domain-dns-name -U user -H hostname-fqdn
6 <!--NeedCopy-->

The user is a domain user with permissions to add machines to the domain. The hostname‑
fqdn is the host name in FQDN format for the machine.

The ‑H option is necessary for adcli to generate SPN in the format of host/hostname‑
fqdn@REALM, which the Linux VDA requires.

3. Verify system keytab.

The capabilities of the adcli tool are limited and do not provide a way to test whether a ma‑
chine is joined to the domain. The best alternative to ensure that the system keytab file has
been created:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 107

Linux Virtual Delivery Agent 1912 LTSR

1 sudo klist -ket

2 <!--NeedCopy-->

Verify that the timestamp for each key matches the time the machine was joined to the domain.

• If you use Samba to join the domain, complete the following steps:

1. Install the package.

1 sudo apt-get install samba

2 <!--NeedCopy-->

2. Configure Samba.

Open /etc/samba/smb.conf, and make the following settings:

1 [global]
2
3 workgroup = WORKGROUP
4
5 security = ADS
6
7 realm = REALM
8
9 client signing = yes
10
11 client use spnego = yes
12
13 kerberos method = secrets and keytab
14 <!--NeedCopy-->

WORKGROUP is the first field in REALM, and REALM is the Kerberos realm name in uppercase.

3. Join the domain with Samba.

Your domain controller must be reachable and you must have a Windows account with permis‑
sions to add computers to the domain.

1 sudo net ads join REALM -U user

2 <!--NeedCopy-->

Where REALM is the Kerberos realm name in uppercase, and user is a domain user with permis‑
sions to add computers to the domain.

Set up SSSD Install or update required packages:

Install the required SSSD and configuration packages if not already installed:

1 sudo apt-get install sssd

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 108

Linux Virtual Delivery Agent 1912 LTSR

If the packages are already installed, an update is recommended:

1 sudo apt-get install --only-upgrade sssd

2 <!--NeedCopy-->

Note:

By default, the install process in Ubuntu automatically configures nsswitch.conf and the PAM
login module.

Configure SSSD SSSD configuration changes are required before starting the SSSD daemon. For
some versions of SSSD, the /etc/sssd/sssd.conf configuration file is not installed by default and must
be manually created. As root, either create or open /etc/sssd/sssd.conf and make the following set‑
tings:

1 [sssd]
2
3 services = nss, pam
4
5 config_file_version = 2
6
7 domains = domain-dns-name
8
9 [domain/domain-dns-name]
10
11 id_provider = ad
12
13 access_provider = ad
14
15 auth_provider = krb5
16
17 krb5_realm = REALM
18
19 # Set krb5_renewable_lifetime higher if TGT renew lifetime is longer
than 14 days
20
21 krb5_renewable_lifetime = 14d
22
23 # Set krb5_renew_interval to lower value if TGT ticket lifetime is
shorter than 2 hours
24
25 krb5_renew_interval = 1h
26
27 krb5_ccachedir = /tmp
28
29 krb5_ccname_template = FILE:%d/krb5cc_%U
30
31 # This ldap_id_mapping setting is also the default value
32
33 ldap_id_mapping = true
34

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 109

Linux Virtual Delivery Agent 1912 LTSR

35 override_homedir = /home/%d/%u
36
37 default_shell = /bin/bash
38
39 ad_gpo_map_remote_interactive = +ctxhdx
40 <!--NeedCopy-->

Note:

ldap_id_mapping is set to true so that SSSD itself takes care of mapping Windows SIDs to Unix
UIDs. Otherwise, the Active Directory must be able to provide POSIX extensions. PAM service
ctxhdx is added to ad_gpo_map_remote_interactive.

The domain-dns-name property in this context is the DNS domain name, such as example.com.
The REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM. There is no require‑
ment to configure the NetBIOS domain name.

Tip:

For information on these configuration settings, see the man pages for sssd.conf and sssd
-ad.

The SSSD daemon requires that the configuration file must have owner read permission only:

1 sudo chmod 0600 /etc/sssd/sssd.conf

2 <!--NeedCopy-->

Start SSSD daemon Run the following commands to start the SSSD daemon now and to enable the
daemon to start upon machine startup:

1 sudo systemctl start sssd

2
3 sudo systemctl enable sssd
4 <!--NeedCopy-->

PAM configuration Run the following command and ensure that the SSS authentication and Cre‑
ate home directory on login options are selected:

1 sudo pam-auth-update
2 <!--NeedCopy-->

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 110

Linux Virtual Delivery Agent 1912 LTSR

• If you use adcli to verify domain membership, run the sudo adcli info domain-dns
-name command to show the domain information.

• If you use Samba to verify domain membership, run the sudo net ads testjoin com‑
mand to verify that the machine is joined to a domain and the sudo net ads info com‑
mand to verify extra domain and computer object information.

Verify Kerberos configuration To verify that Kerberos is configured correctly for use with the Linux
VDA, verify that the system keytab file has been created and contains valid keys:

1 sudo klist -ke

2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

1 sudo kinit -k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

Verify that TGT ticket for the machine account has been cached using:

1 sudo klist
2 <!--NeedCopy-->

Verify user authentication SSSD does not provide a command‑line tool for testing authentication
directly with the daemon, and can only be done via PAM.

To verify that the SSSD PAM module is configured correctly, log on to the Linux VDA using a domain
user account that has not been used before.

1 ssh localhost -l domain\\username

2
3 id -u
4
5 klist
6
7 exit
8 <!--NeedCopy-->

Verify that the Kerberos tickets returned by the klist command are correct for that user and have not
expired.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 111

Linux Virtual Delivery Agent 1912 LTSR

As a root user, verify that a corresponding ticket cache file was created for the uid returned by the
previous id ‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

A similar test can be performed by logging on to KDE or Gnome Display Manager. Proceed to Step 6:
Install the Linux VDA after the domain joining verification.

PBIS

Download the required PBIS package For example:

1 sudo wget https://github.com/BeyondTrust/pbis-open/releases/download

/8.8.0/pbis-open-8.8.0.506.linux.x86_64.deb.sh
2 <!--NeedCopy-->

Make the PBIS installation script executable For example:

1 sudo chmod +x pbis-open-8.8.0.506.linux.x86_64.deb.sh

2 <!--NeedCopy-->

Run the PBIS installation script For example:

1 sudo sh pbis-open-8.8.0.506.linux.x86_64.deb.sh
2 <!--NeedCopy-->

Join Windows domain Your domain controller must be reachable and you must have an Active Di‑
rectory user account with permissions to add computers to the domain:

1 sudo /opt/pbis/bin/domainjoin-cli join domain-name user

2 <!--NeedCopy-->

The user is a domain user who has permissions to add computers to the Active Directory domain. The
domain‑name is the DNS name of the domain, for example, example.com.

Note: To set Bash as the default shell, run the sudo /opt/pbis/bin/config LoginShellTem‑
plate/bin/bash command.

Verify domain membership The Delivery Controller requires that all VDA machines (Windows and
Linux VDAs) have a computer object in Active Directory. To verify that a PBIS‑joined Linux machine is
on the domain:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 112

Linux Virtual Delivery Agent 1912 LTSR

1 /opt/pbis/bin/domainjoin-cli query
2 <!--NeedCopy-->

If the machine is joined to a domain, this command returns the information about the currently joined
AD domain and OU. Otherwise, only the host name appears.

Verify user authentication To verify that PBIS can authenticate domain users through PAM, log on
to the Linux VDA using a domain user account that has not been used before.

1 sudo ssh localhost -l domain\\user

2
3 id -u
4 <!--NeedCopy-->

Verify that a corresponding Kerberos credential cache file was created for the UID returned by the id
‑u command:

1 ls /tmp/krb5cc_uid
2 <!--NeedCopy-->

Exit the session.

1 exit
2 <!--NeedCopy-->

Proceed to Step 6: Install the Linux VDA after the domain joining verification.

Step 4: Install .NET Core Runtime as a prerequisite

Before installing the Linux VDA, install .NET Core Runtime according to the instructions at https://do
cs.microsoft.com/en‑us/dotnet/core/install/linux‑package‑managers.

• For the 1912 LTSR initial release, CU1, and CU2, Install .NET Core Runtime 2.1.
• For CU3 and later releases, install .NET Core Runtime 3.1.

After installing .NET Core Runtime, run the which dotnet command to find your runtime path.

Based on the command output, set the .NET Core runtime binary path. For example, if the command
output is /aa/bb/dotnet, use /aa/bb as the .NET binary path.

Step 5: Download the Linux VDA package

Go to the Citrix Virtual Apps and Desktops download page. Expand the appropriate version of Citrix
Virtual Apps and Desktops and click Components to download the Linux VDA package that matches
your Linux distribution.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 113

Linux Virtual Delivery Agent 1912 LTSR

Step 6: Install the Linux VDA

Step 6a: Install the Linux VDA

Install the Linux VDA software using the Debian package manager:

For Ubuntu 18.04:

1 sudo dpkg -i xendesktopvda_19.12.0.50-1.ubuntu18.04_amd64.deb

2 <!--NeedCopy-->

For Ubuntu 16.04:

1 sudo dpkg -i xendesktopvda_19.12.0.50-1.ubuntu16.04_amd64.deb

2 <!--NeedCopy-->

Debian dependency list for Ubuntu 18.04:

1 postgresql >= 9.5

2
3 libpostgresql-jdbc-java >= 9.2
4
5 openjdk-8-jdk >= 1.8.0
6
7 gtk3-nocsd >=3
8
9 imagemagick >= 8:6.8.9.9
10
11 ufw >= 0.35
12
13 ubuntu-desktop >= 1.361
14
15 libxrandr2 >= 2:1.5.0
16
17 libxtst6 >= 2:1.2.2
18
19 libxm4 >= 2.3.4
20
21 util-linux >= 2.27.1
22
23 bash >= 4.3
24
25 findutils >= 4.6.0
26
27 sed >= 4.2.2
28
29 cups >= 2.1
30
31 libldap-2.4-2 >= 2.4.42
32
33 libsasl2-modules-gssapi-mit >= 2.1.~
34
35 python-requests >= 2.9.1

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 114

Linux Virtual Delivery Agent 1912 LTSR

36
37 libgoogle-perftools4 >= 2.4~
38
39 xserver-xorg-core >= 2:1.18
40
41 xserver-xorg-core << 2:1.19
42
43 x11vnc>=0.9.13
44
45 python-websockify >= 0.6.1
46 <!--NeedCopy-->

Debian dependency list for Ubuntu 16.04:

1 postgresql >= 9.5

2
3 libpostgresql-jdbc-java >= 9.2
4
5 default-jdk >= 2:1.8
6
7 imagemagick >= 8:6.8.9.9
8
9 ufw >= 0.35
10
11 ubuntu-desktop >= 1.361
12
13 libxrandr2 >= 2:1.5.0
14
15 libxtst6 >= 2:1.2.2
16
17 libxm4 >= 2.3.4
18
19 util-linux >= 2.27.1
20
21 bash >= 4.3
22
23 findutils >= 4.6.0
24
25 sed >= 4.2.2
26
27 cups >= 2.1
28
29 libldap-2.4-2 >= 2.4.42
30
31 libsasl2-modules-gssapi-mit >= 2.1.~
32
33 python-requests >= 2.9.1
34
35 libgoogle-perftools4 >= 2.4~
36
37 xserver-xorg-core >= 2:1.18
38
39 xserver-xorg-core << 2:1.19

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 115

Linux Virtual Delivery Agent 1912 LTSR

40
41 x11vnc>=0.9.13
42
43 python-websockify >= 0.6.1
44 <!--NeedCopy-->

Note:

For a matrix of the Linux distributions and the Xorg versions that this version of the Linux VDA
supports, see System requirements.

Step 6b: Upgrade the Linux VDA (optional)

You can upgrade an existing installation from the previous two versions and from an LTSR release.

1 sudo dpkg -i <PATH>/<Linux VDA deb>

2 <!--NeedCopy-->

Step 7: Install NVIDIA GRID drivers

Enabling HDX 3D Pro requires you to install the NVIDIA GRID drivers on your hypervisor and on the VDA
machines.

To install and configure the NVIDIA GRID Virtual GPU Manager (the host driver) on the specific hyper‑
visors, see the following guides:

• Citrix Hypervisor
• VMware ESX

To install and configure the NVIDIA GRID guest VM drivers, perform the following general steps:

1. Ensure that the guest VM is shut down.

2. In the hypervisor control panel, allocate a GPU to the VM.
3. Start the VM.
4. Install the guest VM driver on the VM.

Step 8: Configure the Linux VDA

After installing the package, you must configure the Linux VDA by running the ctxsetup.sh script. Be‑
fore making any changes, the script verifies the environment and ensures that all dependencies are
installed. If necessary, you can rerun the script at any time to change settings.

You can run the script manually with prompting, or automatically with preconfigured responses. Re‑
view Help about the script before proceeding:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 116

Linux Virtual Delivery Agent 1912 LTSR

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh --help

2 <!--NeedCopy-->

Prompted configuration

Run a manual configuration with prompted questions:

1 sudo /opt/Citrix/VDA/sbin/ctxsetup.sh
2 <!--NeedCopy-->

Automated configuration

For an automated install, the options required by the setup script can be provided with environment
variables. If all required variables are present, the script does not prompt the user for any information,
allowing for a scripted installation process.

Supported environment variables include:

• CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N –The Linux VDA supports specifying a Delivery

Controller name using a DNS CNAME record. Set to N by default.
• CTX_XDL_DDC_LIST=’list‑ddc‑fqdns’–The Linux VDA requires a space‑separated list of Deliv‑
ery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Con‑
troller. At least one FQDN or CNAME alias must be specified.
• CTX_XDL_VDA_PORT=port‑number –The Linux VDA communicates with Delivery Controllers
through a TCP/IP port, which is port 80 by default.
• CTX_XDL_REGISTER_SERVICE=Y | N –The Linux Virtual Desktop services are started after ma‑
chine startup. Set to Y by default.
• CTX_XDL_ADD_FIREWALL_RULES=Y | N –The Linux Virtual Desktop services require incoming
network connections to be allowed through the system firewall. You can automatically open the
required ports (ports 80 and 1494 by default) in the system firewall for the Linux Virtual Desktop.
Set to Y by default.
• CTX_XDL_AD_INTEGRATION=1 | 2 | 3 | 4 |5 –The Linux VDA requires Kerberos configuration
settings to authenticate with the Delivery Controllers. The Kerberos configuration is determined
from the installed and configured Active Directory integration tool on the system. Specify the
supported Active Directory integration method to use:

– 1 –Samba Winbind
– 2 –Quest Authentication Services
– 3 –Centrify DirectControl
– 4 –SSSD
– 5 –PBIS

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 117

Linux Virtual Delivery Agent 1912 LTSR

• CTX_XDL_HDX_3D_PRO=Y | N –The Linux VDA supports HDX 3D Pro, a set of GPU acceleration
technologies designed to optimize the virtualization of rich graphics applications. If HDX
3D Pro is selected, the VDA is configured for VDI desktops (single‑session) mode –(that is,
CTX_XDL_VDI_MODE=Y).
• CTX_XDL_VDI_MODE=Y | N –Whether to configure the machine as a dedicated desktop delivery
model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set this
variable to Y. This variable is set to N by default.
• CTX_XDL_SITE_NAME=dns‑name –The Linux VDA discovers LDAP servers through DNS. To
limit the DNS search results to a local site, specify a DNS site name. This variable is set to
<none> by default.
• CTX_XDL_LDAP_LIST=’list‑ldap‑servers’ –The Linux VDA queries DNS to discover LDAP
servers. If DNS cannot provide LDAP service records, you can provide a space‑separated list of
LDAP FQDNs with LDAP port. For example, ad1.mycompany.com:389. This variable is set to
<none> by default.
• CTX_XDL_SEARCH_BASE=search‑base‑set –The Linux VDA queries LDAP through a search
base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com).
However, to improve search performance, you can specify a search base (for example,
OU=VDI,DC=mycompany,DC=com). This variable is set to <none> by default.
• CTX_XDL_FAS_LIST=’list‑fas‑servers’–The Federated Authentication Service (FAS) servers are
configured through AD Group Policy. Because the Linux VDA does not support AD Group Policy,
you can provide a semicolon‑separated list of FAS servers instead. The sequence must be the
same as configured in AD Group Policy. If any server address is removed, fill its blank with the
<none> text string and keep the sequence of server addresses without any changes.
• CTX_XDL_DOTNET_ RUNTIME_PATH=path‑to‑install‑dotnet‑runtime –The path to install
.NET Core Runtime for supporting the new broker agent service (ctxvda). The default path is
/usr/bin.
• CTX_XDL_START_SERVICE=Y | N –Whether or not the Linux VDA services are started when the
Linux VDA configuration is complete. Set to Y by default.

Set the environment variable and run the configure script:

1 export CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N
2
3 export CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’
4
5 export CTX_XDL_VDA_PORT=port-number
6
7 export CTX_XDL_REGISTER_SERVICE=Y|N
8
9 export CTX_XDL_ADD_FIREWALL_RULES=Y|N
10
11 export CTX_XDL_AD_INTEGRATION=1|2|3|4|5
12
13 export CTX_XDL_HDX_3D_PRO=Y|N

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 118

Linux Virtual Delivery Agent 1912 LTSR

14
15 export CTX_XDL_VDI_MODE=Y|N
16
17 export CTX_XDL_SITE_NAME=dns-site-name | '<none>'
18
19 export CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ | '<none>'
20
21 export CTX_XDL_SEARCH_BASE=search-base-set | '<none>'
22
23 export CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ | '<none>'
24
25 export CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime
26
27 export CTX_XDL_START_SERVICE=Y|N
28
29 sudo -E /opt/Citrix/VDA/sbin/ctxsetup.sh
30 <!--NeedCopy-->

When running the sudo command, type the ‑E option to pass the existing environment variables to
the new shell it creates. Citrix recommends that you create a shell script file from the preceding com‑
mands with #!/bin/bash as the first line.

Alternatively, you can specify all parameters by using a single command:

1 sudo CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N \
2
3 CTX_XDL_DDC_LIST= ‘ list-ddc-fqdns ’ \
4
5 CTX_XDL_VDA_PORT=port-number \
6
7 CTX_XDL_REGISTER_SERVICE=Y|N \
8
9 CTX_XDL_ADD_FIREWALL_RULES=Y|N \
10
11 CTX_XDL_AD_INTEGRATION=1|2|3|4|5 \
12
13 CTX_XDL_HDX_3D_PRO=Y|N \
14
15 CTX_XDL_VDI_MODE=Y|N \
16
17 CTX_XDL_SITE_NAME=dns-name \
18
19 CTX_XDL_LDAP_LIST= ‘ list-ldap-servers ’ \
20
21 CTX_XDL_SEARCH_BASE=search-base-set \
22
23 CTX_XDL_FAS_LIST= ‘ list-fas-servers ’ \
24
25 CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime \
26
27 CTX_XDL_START_SERVICE=Y|N \
28
29 /opt/Citrix/VDA/sbin/ctxsetup.sh

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 119

Linux Virtual Delivery Agent 1912 LTSR

30 <!--NeedCopy-->

Remove configuration changes

In some scenarios, you might have to remove the configuration changes made by the ctxsetup.sh
script without uninstalling the Linux VDA package.

Review Help about this script before proceeding:

1 sudo /opt/Citrix/VDA/sbin/ctxcleanup.sh --help

2 <!--NeedCopy-->

To remove configuration changes:

1 sudo /opt/Citrix/VDA/sbin/ctxcleanup.sh
2 <!--NeedCopy-->

Important:

This script deletes all configuration data from the database and renders the Linux VDA inopera‑
ble.

Configuration logs

The ctxsetup.sh and ctxcleanup.sh scripts display errors on the console, with additional information
written to the configuration log file /tmp/xdl.configure.log.

Restart the Linux VDA services to have the changes take effect.

Uninstall the Linux VDA software

To check whether the Linux VDA is installed and to view the version of the installed package:

1 dpkg -l xendesktopvda
2 <!--NeedCopy-->

To view more detailed information:

1 apt-cache show xendesktopvda

2 <!--NeedCopy-->

To uninstall the Linux VDA software:

1 dpkg -r xendesktopvda
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 120

Linux Virtual Delivery Agent 1912 LTSR

Note:

Uninstalling the Linux VDA software deletes the associated PostgreSQL and other configuration
data. However, the PostgreSQL package and other dependent packages that were set up before
the installation of the Linux VDA are not deleted.

Tip:

The information in this section does not cover the removal of dependent packages including
PostgreSQL.

Step 9: Run XDPing

We provide a command‑line utility, the Linux XDPing tool, to check for common configuration is‑
sues with a Linux VDA environment. You can install the XDPing package on any machine running a
supported Linux distribution. XDPing does not require the Linux VDA package to be installed on the
machine. For more information about the tool, see Knowledge Center article CTX202015.

Step 10: Run the Linux VDA

Once you have configured the Linux VDA using the ctxsetup.sh script, you use the following com‑
mands to control the Linux VDA.

Start the Linux VDA:

To start the Linux VDA services:

1 sudo systemctl start ctxhdx

2
3 sudo systemctl start ctxvda
4 <!--NeedCopy-->

Stop the Linux VDA:

To stop the Linux VDA services:

1 sudo systemctl stop ctxvda

2
3 sudo systemctl stop ctxhdx
4 <!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the service ctxmonitorservice
stop command to stop the monitor service daemon. Otherwise, the monitor service daemon
restarts the services you stopped.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 121

Linux Virtual Delivery Agent 1912 LTSR

Restart the Linux VDA:

To restart the Linux VDA services:

1 sudo systemctl stop ctxvda

2
3 sudo systemctl restart ctxhdx
4
5 sudo systemctl restart ctxvda
6 <!--NeedCopy-->

Check the Linux VDA status:

To check the running status of the Linux VDA services:

1 sudo systemctl status ctxvda

2
3 sudo systemctl status ctxhdx
4 <!--NeedCopy-->

Step 11: Create the machine catalog in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating machine catalogs and adding Linux VDA machines is similar to the traditional
Windows VDA approach. For a more detailed description of how to complete these tasks, see Create
machine catalogs and Manage machine catalogs.

For creating machine catalogs that contain Linux VDA machines, there are a few restrictions that dif‑
ferentiate the process from creating machine catalogs for Windows VDA machines:

• For the operating system, select:

– The Multi‑session OS option for a hosted shared desktops delivery model.

– The Single‑session OS option for a VDI dedicated desktop delivery model.

• Do not mix Linux and Windows VDA machines in the same machine catalog.

Note:

Early versions of Citrix Studio did not support the notion of a “Linux OS.”However, selecting the
Windows Server OS or Server OS option implies an equivalent hosted shared desktops deliv‑
ery model. Selecting the Windows Desktop OS or Desktop OS option implies a single user per
machine delivery model.

Tip:

If you remove and rejoin a machine to the Active Directory domain, you must remove and add
the machine to the machine catalog again.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 122

Linux Virtual Delivery Agent 1912 LTSR

Step 12: Create the delivery group in Citrix Virtual Apps or Citrix Virtual Desktops

The process for creating a delivery group and adding machine catalogs containing Linux VDA ma‑
chines is almost identical to Windows VDA machines. For a more detailed description of how to com‑
plete these tasks, see Create Delivery Groups.

For creating delivery groups that contain Linux VDA machine catalogs, the following restrictions ap‑
ply:

• Ensure that the AD users and groups you select have been properly configured to log on to the
Linux VDA machines.
• Do not allow logon of unauthenticated (anonymous) users.
• Do not mix the delivery group with machine catalogs that contain Windows machines.

For information about how to create machine catalogs and delivery groups, see Citrix Virtual Apps
and Desktops 7 1912 LTSR.

Use Machine Creation Services (MCS) to create Linux VMs

April 11, 2023

Starting with the 7.18 release, you can use MCS to create Linux VMs.

Supported hypervisors

• AWS
• Citrix Hypervisor
• Microsoft Azure
• VMware vSphere

Unexpected results can occur if you try to prepare a master image on hypervisors other than the sup‑
ported ones.

Use MCS to create Linux VMs on Citrix Hypervisor

Step 1: Prepare a master image

A master image contains the operating system, non‑virtualized applications, VDA, and other software.
To prepare a master image, do the following:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 123

Linux Virtual Delivery Agent 1912 LTSR

Step 1a: Install Citrix VM Tools Citrix VM Tools must be installed on the template VM for each VM
to be able to use the xe CLI or XenCenter. VM performance can be slow unless the tools are installed.
Without the tools, you cannot do any of the following:

• Cleanly shut down, restart, or suspend a VM.

• View the VM performance data in XenCenter.
• Migrate a running VM (through XenMotion).
• Create snapshots or snapshots with memory (checkpoints), and revert to snapshots.
• Adjust the number of vCPUs on a running Linux VM.

1. Run the following command to mount Citrix VM Tools named guest‑tools.iso.

1 sudo mount /dev/cdrom /mnt

2 <!--NeedCopy-->

2. Run the following command to install the xe-guest-utilities package based on your
Linux distribution.

For RHEL/CentOS:

1 sudo rpm -i /mnt/Linux/xe-guest-utilities_{

2 package-version }
3 _all.rpm
4 <!--NeedCopy-->

For Ubuntu:

1 sudo dpkg -i /mnt/Linux/xe-guest-utilities_{

2 package-version }
3 _all.deb
4 <!--NeedCopy-->

For SUSE 12:

1 sudo rpm -i /mnt/Linux/xe-guest-utilities_{

2 package-version }
3 _all.rpm
4 <!--NeedCopy-->

3. Check the virtualization state of the template VM on the General tab in XenCenter. If Citrix VM
Tools are installed correctly, the virtualization state is Optimized:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 124

Linux Virtual Delivery Agent 1912 LTSR

Step 1b: Install the Linux VDA package on the template VM

Note:

To use a currently running VDA as the template VM, omit this step.

Before installing the Linux VDA package on the template VM, install .NET Core Runtime 3.1. For
more information, see Installation overview.

Based on your Linux distribution, run the following command to set up the environment for the Linux
VDA:
For RHEL/CentOS:

1 sudo yum – y localinstall <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

For Ubuntu:

1 sudo dpkg – i <PATH>/<Linux VDA DEB>

2
3 apt-get install -f
4 <!--NeedCopy-->

For SUSE 12:

1 sudo zypper – i install <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 125

Linux Virtual Delivery Agent 1912 LTSR

Step 1c: Enable repositories to install the tdb‑tools package For RHEL 7 server:

1 subscription-manager repos --enable=rhel-7-server-optional-rpms

2 <!--NeedCopy-->

For RHEL 7 workstation:

1 subscription-manager repos --enable=rhel-7-workstation-optional-rpms

2 <!--NeedCopy-->

Step 1d: Install the EPEL repository that contains ntfs‑3g Install the EPEL repository on RHEL
6/CentOS 6, RHEL 7/CentOS 7 so that running deploymcs.sh later installs the ntfs‑3g package con‑
tained in it.

Step 1e: Manually install ntfs‑3g on SUSE 12 On the SUSE 12 platform, there is no repository pro‑
viding ntfs‑3g. Download the source code, compile, and install ntfs‑3g manually:

1. Install the GNU Compiler Collection (GCC) compiler system and the make package:

1 sudo zypper install gcc

2 sudo zypper install make
3 <!--NeedCopy-->

2. Download the ntfs‑3g package.

3. Decompress the ntfs‑3g package:

1 sudo tar -xvzf ntfs-3g_ntfsprogs-<package version>.tgz

2 <!--NeedCopy-->

4. Enter the path to the ntfs‑3g package:

1 sudo cd ntfs-3g_ntfsprogs-<package version>

2 <!--NeedCopy-->

5. Install ntfs‑3g:

1 ./configure
2 make
3 make install
4 <!--NeedCopy-->

Step 1f: Set up the runtime environment Before running deploymcs.sh, do the following:

• Change variables in /etc/xdl/mcs/mcs.conf. The mcs.conf configuration file contains variables

for setting MCS and the Linux VDA. The following are variables you can set as required:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 126

Linux Virtual Delivery Agent 1912 LTSR

– Use_Existing_Configurations_Of_Current_VDA: Determines whether to use

the existing configurations of the currently running VDA. If set to Y, configuration files
on MCS‑created machines are the same as the equivalents on the currently running VDA.
However, you still must configure the dns and AD_INTEGRATION variables. The default
value is N, which means configuration files on MCS‑created machines are determined by
configuration templates on the master image.
– dns: Sets the DNS IP address.
– AD_INTEGRATION: Sets Winbind or SSSD.
– WORKGROUP: Sets the workgroup name, which is the NetBIOS name (case‑sensitive) if
configured in AD. Otherwise, it is the domain name by default.

• On the template machine, add command lines to the /etc/xdl/mcs/mcs_local_setting.reg file

for writing or updating registry values as required. This action prevents the loss of data and
settings every time an MCS‑provisioned machine restarts.

Each line in the /etc/xdl/mcs/mcs_local_setting.reg file is a command for setting or updating

a registry value.

For example, you can add the following command lines to the /etc/xdl/mcs/mcs_local_setting.reg
file to write or update a registry value respectively:

1 create -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -t "REG_DWORD" -
v "Flags" -d "0x00000003" --force
2 <!--NeedCopy-->

1 update -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -v "Flags" -d "0
x00000003"
2 <!--NeedCopy-->

Step 1g: Create a master image

1. Run /opt/Citrix/VDA/sbin/deploymcs.sh.

2. (Optional) On the template VM, update the configuration templates to customize the relevant
/etc/krb5.conf, /etc/samba/smb.conf, and /etc/sssd/sssd.conf files on all created VMs.

For Winbind users, update the /etc/xdl/mcs/winbind_krb5.conf.tmpl and /etc/xdl/mcs/win‑

bind_smb.conf.tmpl templates.

For SSSD users, update the /etc/xdl/mcs/sssd.conf.tmpl, /etc/xdl/mcs/sssd_krb5.conf.tmpl, and

/etc/xdl/mcs/sssd_smb.conf.tmpl templates.

Note: Keep the existing format used in the template files and use variables such as $WORK‑
GROUP, $REALM, $realm, and $AD_FQDN.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 127

Linux Virtual Delivery Agent 1912 LTSR

3. On Citrix Hypervisor, shut down the template VM. Create and name a snapshot of your master
image.

Step 2: Create a machine catalog

In Citrix Studio, create a machine catalog and specify the number of VMs to create in the catalog. Do
other configuration tasks as needed. For more information, see Create a machine catalog using Stu‑
dio.

Step 3: Create a delivery group

A delivery group is a collection of machines selected from one or more machine catalogs. It specifies
which users can use those machines, and the applications and desktops available to those users. For
more information, see Create delivery groups.

Use MCS to create Linux VMs on Azure

Step 1: Create a hosting connection to Azure in Citrix Studio

1. In Citrix Studio, choose Configuration > Hosting > Add Connection and Resources to create a
connection to Azure.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 128

Linux Virtual Delivery Agent 1912 LTSR

2. Choose Microsoft Azure as the connection type.

3. Type the subscription ID of your Azure account and your connection name.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 129

Linux Virtual Delivery Agent 1912 LTSR

A new connection appears in the hosting pane.

Step 2: Prepare a master image on the template VM

A master image contains the operating system, non‑virtualized applications, VDA, and other software.
To prepare a master image, do the following:

Step 2a: Configure cloud‑init for Ubuntu 18.04 To ensure that a VDA host name persists when a
VM is restarted or stopped, run the following command.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 130

Linux Virtual Delivery Agent 1912 LTSR

1 echo "preserve_hostname: true" > /etc/cloud/cloud.cfg.d/99_hostname.

cfg
2 <!--NeedCopy-->

Ensure that the following lines are present under the system_info section in the /etc/cloud/cloud.cfg
file:

1 system_info:
2 network:
3 renderers: ['netplan', 'eni', 'sysconfig']
4 <!--NeedCopy-->

Step 2b: Install the Linux VDA package on the template VM

Note:

To use a currently running VDA as the template VM, omit this step.

Before installing the Linux VDA package on the template VM, install .NET Core Runtime 3.1. For
more information, see Installation overview.

Based on your Linux distribution, run the following command to set up the environment for the Linux
VDA:
For RHEL/CentOS:

1 sudo yum – y localinstall <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

For Ubuntu:

1 sudo dpkg – i <PATH>/<Linux VDA DEB>

2
3 apt-get install -f
4 <!--NeedCopy-->

For SUSE 12:

1 sudo zypper – i install <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

Step 2c: Enable repositories to install the tdb‑tools package For RHEL 7 server:

1 subscription-manager repos --enable=rhel-7-server-optional-rpms

2 <!--NeedCopy-->

For RHEL 7 workstation:

1 subscription-manager repos --enable=rhel-7-workstation-optional-rpms

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 131

Linux Virtual Delivery Agent 1912 LTSR

Step 2d: Install the EPEL repository that contains ntfs‑3g Install the EPEL repository on RHEL
6/CentOS 6, RHEL 7/CentOS 7 so that running deploymcs.sh later installs the ntfs‑3g package con‑
tained in it.

Step 2e: Manually install ntfs‑3g on SUSE 12 On the SUSE 12 platform, there is no repository pro‑
viding ntfs‑3g. Download the source code, compile, and install ntfs‑3g manually:

1. Install the GNU Compiler Collection (GCC) compiler system and the make package:

1 sudo zypper install gcc

2 sudo zypper install make
3 <!--NeedCopy-->

2. Download the ntfs‑3g package.

3. Decompress the ntfs‑3g package:

1 sudo tar -xvzf ntfs-3g_ntfsprogs-<package version>.tgz

2 <!--NeedCopy-->

4. Enter the path to the ntfs‑3g package:

1 sudo cd ntfs-3g_ntfsprogs-<package version>

2 <!--NeedCopy-->

5. Install ntfs‑3g:

1 ./configure
2 make
3 make install
4 <!--NeedCopy-->

Step 2f: Set up the runtime environment Before running deploymcs.sh, do the following:

• Change variables in /etc/xdl/mcs/mcs.conf. The mcs.conf configuration file contains variables

for setting MCS and the Linux VDA. The following are some of the variables, of which dns and
AD_INTEGRATION must be set:

Note: If a variable can be set with multiple values, put the values inside single quotes and sep‑
arate them with spaces. For example, LDAP_LIST=’aaa.lab:389 bbb.lab:389.’

– Use_Existing_Configurations_Of_Current_VDA: Determines whether to use

the existing configurations of the currently running VDA. If set to Y, configuration files
on MCS‑created machines are the same as the equivalents on the currently running VDA.
However, you still must configure the dns and AD_INTEGRATION variables. The default
value is N, which means configuration files on MCS‑created machines are determined by
configuration templates on the master image.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 132

Linux Virtual Delivery Agent 1912 LTSR

– dns: Sets the DNS IP address.

– AD_INTEGRATION: Sets Winbind or SSSD (SSSD is not supported on SUSE).
– WORKGROUP: Sets the workgroup name, which is the NetBIOS name (case‑sensitive) if
configured in AD. Otherwise, it is the domain name by default.

• On the template machine, add command lines to the /etc/xdl/mcs/mcs_local_setting.reg file

for writing or updating registry values as required. This action prevents the loss of data and
settings every time an MCS‑provisioned machine restarts.

Each line in the /etc/xdl/mcs/mcs_local_setting.reg file is a command for setting or updating

a registry value.

For example, you can add the following command lines to the /etc/xdl/mcs/mcs_local_setting.reg
file to write or update a registry value respectively:

1 create -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -t "REG_DWORD" -
v "Flags" -d "0x00000003" --force
2 <!--NeedCopy-->

1 update -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -v "Flags" -d "0
x00000003"
2 <!--NeedCopy-->

Step 2g: Create a master image

1. Run /opt/Citrix/VDA/sbin/deploymcs.sh.

2. (Optional) On the template VM, update the configuration templates to customize the relevant
/etc/krb5.conf, /etc/samba/smb.conf, and /etc/sssd/sssd.conf files on all created VMs.

For Winbind users, update the /etc/xdl/mcs/winbind_krb5.conf.tmpl and /etc/xdl/mcs/win‑

bind_smb.conf.tmpl templates.

For SSSD users, update the /etc/xdl/mcs/sssd.conf.tmpl, /etc/xdl/mcs/sssd_krb5.conf.tmpl, and

/etc/xdl/mcs/sssd_smb.conf.tmpl templates.

Note: Keep the existing format used in the template files and use variables such as $WORK‑
GROUP, $REALM, $realm, and $AD_FQDN.

3. Install applications on the template VM and shut down the template VM from the Azure por‑
tal. Ensure that the power status of the template VM is Stopped (deallocated). Remember the
name of the resource group here. You need the name to locate your master image on Azure.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 133

Linux Virtual Delivery Agent 1912 LTSR

Step 3: Create a machine catalog

In Citrix Studio, create a machine catalog and specify the number of VMs to create in the catalog. When
creating the machine catalog, choose your master image from the resource group where the template
VM belongs and find the VHD of the template VM. See the following screen capture.

Do other configuration tasks as needed. For more information, see Create a machine catalog using
Studio.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 134

Linux Virtual Delivery Agent 1912 LTSR

Step 4: Create a delivery group

A delivery group is a collection of machines selected from one or more machine catalogs. It specifies
which users can use those machines, and the applications and desktops available to those users. For
more information, see Create delivery groups.

Use MCS to create Linux VMs on VMware vSphere

Step 1: Create a hosting connection to VMware in Citrix Studio

1. Install vCenter Server in the vSphere environment. For more information, see VMware vSphere.

2. In Citrix Studio, choose Configuration > Hosting > Add Connection and Resources to create a
connection to VMware vSphere.

3. Choose VMware vSphere as the connection type.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 135

Linux Virtual Delivery Agent 1912 LTSR

4. Type the connection address (the vCenter Server URL) of your VMware account, your user name
and password, and your connection name.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 136

Linux Virtual Delivery Agent 1912 LTSR

A new connection appears in the hosting pane.

Step 2: Prepare a master image

A master image contains the operating system, non‑virtualized applications, VDA, and other software.
To prepare a master image, do the following:

Step 2a: Install the Linux VDA package on the template VM

Note:

To use a currently running VDA as the template VM, omit this step.

Before installing the Linux VDA package on the template VM, install .NET Core Runtime 3.1. For

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 137

Linux Virtual Delivery Agent 1912 LTSR

more information, see Installation overview.

Based on your Linux distribution, run the following command to set up the environment for the Linux
VDA:

For RHEL/CentOS:

1 sudo yum – y localinstall <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

For Ubuntu:

1 sudo dpkg – i <PATH>/<Linux VDA DEB>

2
3 apt-get install -f
4 <!--NeedCopy-->

For SUSE 12:

1 sudo zypper – i install <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

Step 2b: Enable repositories to install the tdb‑tools package For RHEL 7 server:

1 subscription-manager repos --enable=rhel-7-server-optional-rpms

2 <!--NeedCopy-->

For RHEL 7 workstation:

1 subscription-manager repos --enable=rhel-7-workstation-optional-rpms

2 <!--NeedCopy-->

Step 2c: Install the EPEL repository that contains ntfs‑3g Install the EPEL repository on RHEL
6/CentOS 6, RHEL 7/CentOS 7 so that running deploymcs.sh later installs the ntfs‑3g package con‑
tained in it.

Step 2d: Manually install ntfs‑3g on SUSE 12 On the SUSE 12 platform, there is no repository pro‑
viding ntfs‑3g. Download the source code, compile, and install ntfs‑3g manually:

1. Install the GNU Compiler Collection (GCC) compiler system and the make package:

1 sudo zypper install gcc

2 sudo zypper install make
3 <!--NeedCopy-->

2. Download the ntfs‑3g package.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 138

Linux Virtual Delivery Agent 1912 LTSR

3. Decompress the ntfs‑3g package:

1 sudo tar -xvzf ntfs-3g_ntfsprogs-<package version>.tgz

2 <!--NeedCopy-->

4. Enter the path to the ntfs‑3g package:

1 sudo cd ntfs-3g_ntfsprogs-<package version>

2 <!--NeedCopy-->

5. Install ntfs‑3g:

1 ./configure
2 make
3 make install
4 <!--NeedCopy-->

Step 2e: Set up the runtime environment Before running deploymcs.sh, do the following:

• Change variables in /etc/xdl/mcs/mcs.conf. The mcs.conf configuration file contains variables

for setting MCS and the Linux VDA. The following are some of the variables, of which dns and
AD_INTEGRATION must be set:

Note: If a variable can be set with multiple values, put the values inside single quotes and sep‑
arate them with spaces. For example, LDAP_LIST=’aaa.lab:389 bbb.lab:389.’

– Use_Existing_Configurations_Of_Current_VDA: Determines whether to use

the existing configurations of the currently running VDA. If set to Y, the configuration files
on MCS‑created machines are the same as the equivalents on the currently running VDA.
However, you still must configure the dns and AD_INTEGRATION variables. The default
value is N, which means the configuration files on MCS‑created machines are determined
by the configuration templates on the master image.
– dns: Sets the DNS IP address.
– AD_INTEGRATION: Sets Winbind or SSSD (SSSD is not supported on SUSE).
– WORKGROUP: Sets the workgroup name, which is the NetBIOS name (case‑sensitive) if
configured in AD. Otherwise, it is the domain name by default.

• On the template machine, add command lines to the /etc/xdl/mcs/mcs_local_setting.reg file

for writing or updating registry values as required. This action prevents the loss of data and
settings every time an MCS‑provisioned machine restarts.

Each line in the /etc/xdl/mcs/mcs_local_setting.reg file is a command for setting or updating

a registry value.

For example, you can add the following command lines to the /etc/xdl/mcs/mcs_local_setting.reg
file to write or update a registry value respectively:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 139

Linux Virtual Delivery Agent 1912 LTSR

1 create -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -t "REG_DWORD" -
v "Flags" -d "0x00000003" --force
2 <!--NeedCopy-->

1 update -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -v "Flags" -d "0
x00000003"
2 <!--NeedCopy-->

Step 2f: Create a master image

1. Run /opt/Citrix/VDA/sbin/deploymcs.sh.

2. (Optional) On the template VM, update the configuration templates to customize the relevant
/etc/krb5.conf, /etc/samba/smb.conf, and /etc/sssd/sssd.conf files on all created VMs.

For Winbind users, update the /etc/xdl/mcs/winbind_krb5.conf.tmpl and /etc/xdl/mcs/win‑

bind_smb.conf.tmpl templates.

For SSSD users, update the /etc/xdl/mcs/sssd.conf.tmpl, /etc/xdl/mcs/sssd_krb5.conf.tmpl, and

/etc/xdl/mcs/sssd_smb.conf.tmpl templates.

Note: Keep the existing format used in the template files and use variables such as $WORK‑
GROUP, $REALM, $realm, and $AD_FQDN.

3. After you finish installing applications on the template VM, shut down the template VM from the
VMware. Take a snapshot of the template VM.

Step 3: Create a machine catalog

In Citrix Studio, create a machine catalog and specify the number of VMs to create in the catalog. When
creating the machine catalog, choose your master image from the snapshot list.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 140

Linux Virtual Delivery Agent 1912 LTSR

Do other configuration tasks as needed. For more information, see Create a machine catalog using
Studio.

Step 4: Create a delivery group

A delivery group is a collection of machines selected from one or more machine catalogs. The delivery
group specifies which users can use those machines, and the applications and desktops available to
those users. For more information, see Create delivery groups.

Use MCS to create Linux VMs on AWS

Step 1: Create a hosting connection to AWS in Citrix Studio

1. In Citrix Studio, choose Configuration > Hosting > Add Connection and Resources to create a
connection to AWS.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 141

Linux Virtual Delivery Agent 1912 LTSR

2. Choose Amazon EC2 as the connection type.

3. Type the API key and secret key of your AWS account and type your connection name.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 142

Linux Virtual Delivery Agent 1912 LTSR

The API key is your access key ID and the Secret key is your secret access key. They are consid‑
ered as an access key pair. If you lose your secret access key, you can delete the access key and
create a new one. To create an access key, do the following:

a) Sign in to the AWS services.

b) Navigate to the Identity and Access Management (IAM) console.
c) On the left navigation pane, choose Users.
d) Select the target user and scroll down to select the Security credentials tab.
e) Scroll down and click Create access key. A new window appears.
f) Click Download .csv file and save the access key to a secure location.

A new connection appears in the hosting pane.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 143

Linux Virtual Delivery Agent 1912 LTSR

Step 2: Prepare a master image

A master image contains the operating system, non‑virtualized applications, VDA, and other software.
To prepare a master image, do the following:

Step 2a: Configure cloud‑init

1. To ensure that a VDA host name persists when an EC2 instance is restarted or stopped, run the
following command to preserve the VDA host name.

1 echo "preserve_hostname: true" > /etc/cloud/cloud.cfg.d/99

_hostname.cfg
2 <!--NeedCopy-->

For Ubuntu 18.04, ensure that the following lines are present under the system_info section in
the /etc/cloud/cloud.cfg file:

1 system_info:
2 network:
3 renderers: ['netplan', 'eni', 'sysconfig']
4 <!--NeedCopy-->

2. To use SSH for remotely accessing MCS‑created VMs on AWS, enable password authentication
because no key name is attached to those VMs. Do the following as needed.

• Edit the cloud‑init configuration file, /etc/cloud/cloud.cfg. Ensure that the ssh_pwauth:
true line is present. Remove or comment the set‑password line and the following lines if
they exist.

1 users:
2 - default
3 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 144

Linux Virtual Delivery Agent 1912 LTSR

• If you plan to use the default user ec2-user or ubuntu created by cloud‑init, you can
change the user password by using the passwd command. Keep the new password in
mind for later use to log in to the MCS‑created VMs.

• Edit the /etc/ssh/sshd_config file to ensure that the following line is present:

1 PasswordAuthentication yes
2 <!--NeedCopy-->

Save the file and run the sudo service sshd restart command.

Step 2b: Install the Linux VDA package on the template VM

Note:

To use a currently running VDA as the template VM, omit this step.

Before installing the Linux VDA package on the template VM, install .NET Core Runtime 3.1. For
more information, see Installation overview.

Based on your Linux distribution, run the following command to set up the environment for the Linux
VDA:

For RHEL/CentOS:

1 sudo yum – y localinstall <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

For Ubuntu:

1 sudo dpkg – i <PATH>/<Linux VDA DEB>

2
3 apt-get install -f
4 <!--NeedCopy-->

For SUSE 12:

1 sudo zypper – i install <PATH>/<Linux VDA RPM>

2 <!--NeedCopy-->

Step 2c: Enable repositories to install the tdb‑tools package For RHEL 7 server:

1 subscription-manager repos --enable=rhel-7-server-optional-rpms

2 <!--NeedCopy-->

For RHEL 7 workstation:

1 subscription-manager repos --enable=rhel-7-workstation-optional-rpms

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 145

Linux Virtual Delivery Agent 1912 LTSR

Step 2d: Install the EPEL repository that contains ntfs‑3g Install the EPEL repository on RHEL
6/CentOS 6, RHEL 7/CentOS 7 so that running deploymcs.sh later installs the ntfs‑3g package con‑
tained in it.

Step 2e: Manually install ntfs‑3g on SUSE 12 On the SUSE 12 platform, there is no repository pro‑
viding ntfs‑3g. Download the source code, compile, and install ntfs‑3g manually:

1. Install the GNU Compiler Collection (GCC) compiler system and the make package:

1 sudo zypper install gcc

2 sudo zypper install make
3 <!--NeedCopy-->

2. Download the ntfs‑3g package.

3. Decompress the ntfs‑3g package:

1 sudo tar -xvzf ntfs-3g_ntfsprogs-<package version>.tgz

2 <!--NeedCopy-->

4. Enter the path to the ntfs‑3g package:

1 sudo cd ntfs-3g_ntfsprogs-<package version>

2 <!--NeedCopy-->

5. Install ntfs‑3g:

1 ./configure
2 make
3 make install
4 <!--NeedCopy-->

Step 2f: Set up the runtime environment Before running deploymcs.sh, do the following:

• Change variables in /etc/xdl/mcs/mcs.conf. The mcs.conf configuration file contains variables

for setting MCS and the Linux VDA. The following are some of the variables, of which dns and
AD_INTEGRATION must be set:

Note: If a variable can be set with multiple values, put the values inside single quotes and sep‑
arate them with spaces. For example, LDAP_LIST=’aaa.lab:389 bbb.lab:389.’

– Use_Existing_Configurations_Of_Current_VDA: Determines whether to use

the existing configurations of the currently running VDA. If set to Y, configuration files
on MCS‑created machines are the same as the equivalents on the currently running VDA.
However, you still must configure the dns and AD_INTEGRATION variables. The default
value is N, which means configuration files on MCS‑created machines are determined by
configuration templates on the master image.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 146

Linux Virtual Delivery Agent 1912 LTSR

– dns: Sets the DNS IP address.

– AD_INTEGRATION: Sets Winbind or SSSD (SSSD is not supported on SUSE).
– WORKGROUP: Sets the workgroup name, which is the NetBIOS name (case‑sensitive) if
configured in AD. Otherwise, it is the domain name by default.

• On the template machine, add command lines to the /etc/xdl/mcs/mcs_local_setting.reg file

for writing or updating registry values as required. This action prevents the loss of data and
settings every time an MCS‑provisioned machine restarts.

Each line in the /etc/xdl/mcs/mcs_local_setting.reg file is a command for setting or updating

a registry value.

For example, you can add the following command lines to the /etc/xdl/mcs/mcs_local_setting.reg
file to write or update a registry value respectively:

1 create -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -t "REG_DWORD" -
v "Flags" -d "0x00000003" --force
2 <!--NeedCopy-->

1 update -k "HKLM\System\CurrentControlSet\Control\Citrix\
VirtualChannels\Clipboard\ClipboardSelection" -v "Flags" -d "0
x00000003"
2 <!--NeedCopy-->

Step 2g: Create a master image

1. Run /opt/Citrix/VDA/sbin/deploymcs.sh.

2. (Optional) On the template VM, update the configuration templates to customize the relevant
/etc/krb5.conf, /etc/samba/smb.conf, and /etc/sssd/sssd.conf files on all created VMs.

For Winbind users, update the /etc/xdl/mcs/winbind_krb5.conf.tmpl and /etc/xdl/mcs/win‑

bind_smb.conf.tmpl templates.

For SSSD users, update the /etc/xdl/mcs/sssd.conf.tmpl, /etc/xdl/mcs/sssd_krb5.conf.tmpl, and

/etc/xdl/mcs/sssd_smb.conf.tmpl templates.

Note: Keep the existing format used in the template files and use variables such as $WORK‑
GROUP, $REALM, $realm, and $AD_FQDN.

3. Install applications on the template VM and shut down the template VM from the AWS EC2 portal.
Ensure that the instance state of the template VM is Stopped.

4. Right‑click the template VM and select Image > Create Image. Type information and make set‑
tings as needed. Click Create Image.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 147

Linux Virtual Delivery Agent 1912 LTSR

Step 3: Create a machine catalog

In Citrix Studio, create a machine catalog and specify the number of VMs to create in the catalog. When
creating the machine catalog, choose your machine template (the master image you created earlier)
and select one or more security groups.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 148

Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 149

Linux Virtual Delivery Agent 1912 LTSR

Do other configuration tasks as needed. For more information, see Create a machine catalog using
Studio.

Step 4: Create a delivery group

A delivery group is a collection of machines selected from one or more machine catalogs. It specifies
which users can use those machines, and the applications and desktops available to those users. For
more information, see Create delivery groups.

Use MCS to upgrade your Linux VDA

To use MCS to upgrade your Linux VDA, do the following:

1. Upgrade your Linux VDA on the template machine:

For RHEL 7/CentOS 7:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.el7_x.x86_64.rpm

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 150

Linux Virtual Delivery Agent 1912 LTSR

For RHEL 6/CentOS 6:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.el6_x.x86_64.rpm

2 <!--NeedCopy-->

For SUSE 12:

1 sudo rpm -U XenDesktopVDA-19.12.0.50-1.sle12_x.x86_64.rpm

2 <!--NeedCopy-->

For Ubuntu 16.04:

1 sudo dpkg -i xendesktopvda_19.12.0.50-1.ubuntu16.04_amd64.deb

2 <!--NeedCopy-->

For Ubuntu 18.04:

1 sudo dpkg -i xendesktopvda_19.12.0.50-1.ubuntu18.04_amd64.deb

2 <!--NeedCopy-->

2. Edit /etc/xdl/mcs/mcs.conf and /etc/xdl/mcs/mcs_local_setting.reg.

3. Take a new snapshot.

4. In Citrix Studio, select the new snapshot to update your machine catalog. Wait before each
machine restarts. Do not restart a machine manually.

Configure the Linux VDA

April 8, 2021

This section details the features of the Linux VDA, including feature description, configuration, and
troubleshooting.

Tip:

The xdlcollect Bash script used to collect logs is integrated into the Linux VDA software and
located under /opt/Citrix/VDA/bin. After you install the Linux VDA, you can run the bash /opt
/Citrix/VDA/bin/xdlcollect.sh command to collect logs.

After log collection completes, a compressed log file is generated in the same folder as the script.
xdlcollect can ask you whether or not to upload the compressed log file to Citrix Insight
Services (CIS). If you agree, xdlcollect returns an upload_ID after the upload completes. The
upload does not remove the compressed log file from your local machine. Other users can use
the upload_ID to access the log file in CIS.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 151

Linux Virtual Delivery Agent 1912 LTSR

Integrate NIS with Active Directory

June 18, 2020

This article describes how to integrate NIS with Windows Active Directory (AD) on the Linux VDA by
using SSSD. The Linux VDA is considered a component of Citrix Virtual Apps and Desktops. As a result,
it fits tightly into the Windows AD environment.

Using NIS as a UID and GID provider instead of using AD requires that the account information (user
name and password combinations) is the same in both AD and NIS.
Note:

Authentication is still performed by the AD server. NIS+ is not supported. If you use NIS as the
UID and GID provider, the POSIX attributes from the Windows server are no longer used.

Tip:

This method represents a deprecated way to deploy the Linux VDA, which is used only for special
use cases. For an RHEL/CentOS distribution, follow the instructions in Install Linux Virtual Deliv‑
ery Agent for RHEL/CentOS. For an Ubuntu distribution, follow the instructions in Install Linux
Virtual Delivery Agent for Ubuntu.

What is SSSD?

SSSD is a system daemon. Its primary function is to provide access to identify and authenticate re‑
mote resources through a common framework that can provide caching and offline support for the
system. It provides both PAM and NSS modules, and in the future can support D‑BUS based interfaces
for extended user information. It also provides a better database to store local user accounts and
extended user data.

Required software

The AD provider was first introduced with SSSD Version 1.9.0.

The following environments have been tested and verified when you use the instructions included in
this article:

• RHEL 7.7 and later

• CentOS 7.7 and later

Integrate NIS with AD

To integrate NIS with AD, do the following:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 152

Linux Virtual Delivery Agent 1912 LTSR

1. Add the Linux VDA as a NIS client

2. Join the domain and create a host keytab using Samba
3. Set up SSSD
4. Configure NSS/PAM
5. Verify the Kerberos configuration
6. Verify user authentication

Add the Linux VDA as a NIS client

Configure the NIS client:

1 yum – y install ypbind rpcbind oddjob-mkhomedir

2 <!--NeedCopy-->

Set the NIS domain:

1 ypdomainname nis.domain
2 echo "NISDOMAIN=nis.domain" >> /etc/sysconfig/network
3 <!--NeedCopy-->

Add the IP address for the NIS server and client in /etc/hosts:

{ NIS server IP address } server.nis.domain nis.domain

Configure NIS by authconfig:

1 sudo authconfig --enablenis --nisdomain=nis.domain --nisserver=server.

nis.domain --enablemkhomedir --update
2 <!--NeedCopy-->

The nis.domain represents the domain name of the NIS server. The server.nis.domain is the host
name of the NIS server, which can also be the IP address of the NIS server.

Configure the NIS services:

1 sudo systemctl start rpcbind ypbind

2
3 sudo systemctl enable rpcbind ypbind
4 <!--NeedCopy-->

Ensure that the NIS configuration is correct:

1 ypwhich
2 <!--NeedCopy-->

Validate that the account information is available from the NIS server:

1 getent passwd nisaccount

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 153

Linux Virtual Delivery Agent 1912 LTSR

Note:

The nisaccount represents the real NIS account on the NIS server. Ensure that the UID, GID, home
directory, and login shell are configured correctly.

Join the domain and create a host keytab using Samba

SSSD does not provide AD client functions for joining the domain and managing the system keytab
file. There are a few methods for achieving the functions, including:

• adcli
• realmd
• Winbind
• Samba

The information in this section describes the Samba approach only. For realmd, see the RHEL or
CentOS vendor’s documentation. These steps must be followed before configuring SSSD.
Join the domain and create host keytab using Samba:
On the Linux client with properly configured files:

• /etc/krb5.conf
• /etc/samba/smb.conf:

Configure the machine for Samba and Kerberos authentication:

1 sudo authconfig --smbsecurity=ads --smbworkgroup=domain --smbrealm=

REALM --krb5realm=REALM --krb5kdc=fqdn-of-domain-controller --update
2 <!--NeedCopy-->

Where REALM is the Kerberos realm name in uppercase and domain is the NetBIOS name of the do‑
main.
If DNS‑based lookup of the KDC server and realm name is required, add the following two options to
the preceding command:
--enablekrb5kdcdns --enablekrb5realmdns
Open /etc/samba/smb.conf and add the following entries under the [Global] section, but after the
section generated by the authconfig tool:
kerberos method = secrets and keytab
Joining the Windows domain requires that your domain controller is reachable and you have an AD
user account with permissions to add computers to the domain:

1 sudo net ads join REALM -U user

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 154

Linux Virtual Delivery Agent 1912 LTSR

REALM is the Kerberos realm name in uppercase and user is a domain user who has permissions to
add computers to the domain.

Set up SSSD

Setting up SSSD consists of the following steps:

• Install the sssd‑ad and sssd‑proxy packages on the Linux client machine.
• Make configuration changes to various files (for example, sssd.conf).
• Start the sssd service.

/etc/sssd/sssd.conf An example sssd.conf configuration (more options can be added as

needed):

1 [sssd]
2 config_file_version = 2
3 domains = EXAMPLE
4 services = nss, pam
5
6 [domain/EXAMPLE]
7 # Uncomment if you need offline logins
8 # cache_credentials = true
9 re_expression = (((?P<domain>[^\\]+)\\(?P<name>.+$))|((?P<name>[^@]+)@
(?P<domain>.+$))|(^(?P<name>[^@\\]+)$))
10 id_provider = proxy
11 proxy_lib_name = nis
12 auth_provider = ad
13 access_provider = ad
14
15 # Should be specified as the long version of the Active Directory
domain.
16 ad_domain = EXAMPLE.COM
17
18 # Kerberos settings
19 krb5_ccachedir = /tmp
20 krb5_ccname_template = FILE:%d/krb5cc_%U
21
22 # Uncomment if service discovery is not working
23 # ad_server = server.ad.example.com
24
25 # Comment out if the users have the shell and home dir set on the AD
side
26 default_shell = /bin/bash
27 fallback_homedir = /home/%d/%u
28
29 # Uncomment and adjust if the default principal SHORTNAME$@REALM is not
available
30 # ldap_sasl_authid = host/client.ad.example.com@AD.EXAMPLE.COM
31 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 155

Linux Virtual Delivery Agent 1912 LTSR

Replace ad.domain.com, server.ad.example.com with the corresponding value. For more details,
see the sssd‑ad(5) ‑ Linux man page.
Set the file ownership and permissions on sssd.conf:
chown root:root /etc/sssd/sssd.conf
chmod 0600 /etc/sssd/sssd.conf
restorecon /etc/sssd/sssd.conf

Configure NSS/PAM

RHEL/CentOS:
Use authconfig to enable SSSD. Install oddjob‑mkhomedir to ensure that the home directory cre‑
ation is compatible with SELinux:

1 authconfig --enablesssd --enablesssdauth --enablemkhomedir --update

2
3 sudo systemctl start sssd
4
5 sudo systemctl enable sssd
6 <!--NeedCopy-->

Tip:

When configuring Linux VDA settings, consider that for SSSD, there has no special settings for the
Linux VDA client. For extra solutions in the ctxsetup.sh script, use the default value.

Verify the Kerberos configuration

To ensure that Kerberos is configured correctly for use with the Linux VDA, check that the system
keytab file has been created and contains valid keys:

1 sudo klist -ke

2 <!--NeedCopy-->

This command displays the list of keys available for the various combinations of principal names and
cipher suites. Run the Kerberos kinit command to authenticate the machine with the domain con‑
troller using these keys:

1 sudo kinit – k MACHINE\$@REALM

2 <!--NeedCopy-->

The machine and realm names must be specified in uppercase. The dollar sign ($) must be escaped
with a backslash (\) to prevent shell substitution. In some environments, the DNS domain name is
different from the Kerberos realm name. Ensure that the realm name is used. If this command is
successful, no output is displayed.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 156

Linux Virtual Delivery Agent 1912 LTSR

Verify that the TGT ticket for the machine account has been cached using:

1 sudo klist -ke

2 <!--NeedCopy-->

Verify user authentication

Use the getent command to verify that the logon format is supported and whether the NSS works:

1 sudo getent passwd DOMAIN\\username

2 <!--NeedCopy-->

The DOMAIN parameter indicates the short version domain name. If another logon format is needed,
verify by using the getent command first.

The supported logon formats are:

• Down‑level logon name: DOMAIN\username

• UPN: username@domain.com
• NetBIOS Suffix format: username@DOMAIN

To verify that the SSSD PAM module is configured correctly, use a domain user account to log on to
the Linux VDA. The domain user account has not been used before.

1 sudo ssh localhost – l DOMAIN\\username

2
3 id -u
4 <!--NeedCopy-->

Check that a corresponding Kerberos credential cache file was created for the uid returned by the
command:

1 ls /tmp/krb5cc_{
2 uid }
3
4 <!--NeedCopy-->

Check that the tickets in the user’s Kerberos credential cache are valid and not expired:

1 klist
2 <!--NeedCopy-->

Publish applications

June 22, 2022

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 157

Linux Virtual Delivery Agent 1912 LTSR

With Linux VDA Version 7.13, Citrix added the seamless applications feature to all the supported Linux
platforms. No specific installation procedures are required to use this feature.

Tip:

With Linux VDA version 1.4, Citrix added support for non‑seamless published applications and
session sharing.

Publish applications using Citrix Studio

You can publish applications installed on a Linux VDA when you create a delivery group or add appli‑
cations to an existing delivery group. The process is similar to publishing applications installed on a
Windows VDA. For more information, see the Citrix Virtual Apps and Desktops documentation (based
on the version of Citrix Virtual Apps and Desktops being used).

Tip:

When configuring delivery groups, ensure that the delivery type is set to Desktop and applica‑
tions or Applications.

Important:

Publishing applications is supported with Linux VDA Version 1.4 and later. However, the Linux
VDA does not support the delivery of desktops and apps to the same machine. To address this
issue, Citrix recommends that you create separate delivery groups for app and desktop deliver‑
ies.

Note:

To use seamless applications, do not disable the seamless mode on StoreFront. The seamless
mode is enabled by default. If you have already disabled it by setting “TWIMode=Off,”remove
this setting instead of changing it to “TWIMode=On.”Otherwise you might not be able to launch
a published desktop.

Limitation

The Linux VDA does not support the launch of multiple concurrent instances of the same application
by a single user.

Known issues

The following known issues are identified during publishing applications:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 158

Linux Virtual Delivery Agent 1912 LTSR

• Non‑rectangular windows are not supported. The corners of a window might show the server‑
side background.
• Preview of the content of a window from a published application is not supported.
• Currently, the seamless mode supports the following Window Managers: Mutter, Metacity, and
Compiz (Ubuntu 16.04). Kwin and other window managers are not supported. Ensure that your
window manager is set a supported one.
• When you run multiple LibreOffice applications, only the one launched first shows on Citrix Stu‑
dio because these applications share the process.
• Published Qt5‑based applications like “Dolphin”might not show icons. To resolve the issue, see
the article at https://wiki.archlinux.org/title/Qt.
• All the taskbar buttons of published applications running in the same ICA session are combined
in the same group. To resolve this issue, set the taskbar property not to combine taskbar but‑
tons.

Remote PC Access

July 8, 2020

Overview

Remote PC Access is an extension of Citrix Virtual Apps and Desktops. It enables organizations to easily
allow employees to access their physical office PCs remotely in a secure manner. If users can access
their office PCs, they can access all the applications, data, and resources they need to do their work.

Remote PC Access uses the same Citrix Virtual Apps and Desktops components that deliver virtual
desktops and applications. The requirements and process of deploying and configuring Remote PC
Access are the same as the requirements and process required for deploying Citrix Virtual Apps and
Desktops for the delivery of virtual resources. This uniformity provides a consistent and unified ad‑
ministrative experience. Users receive the best user experience by using Citrix HDX to deliver their
remote office PC sessions.

For more information, see Remote PC Access in the Citrix Virtual Apps and Desktops documentation.

Configuration

To deliver Linux PC sessions, install the Linux VDA on target PCs, create a machine catalog of the Re‑
mote PC Access type, and create a Delivery Group to make the PCs in the machine catalog available
for users who request access. The following section details the procedure:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 159

Linux Virtual Delivery Agent 1912 LTSR

Step 1 ‑ Install the Linux VDA on target PCs

We recommend you use easy install to install the Linux VDA. During the installation, set the value of
the CTX_XDL_VDI_MODE variable to Y.

Step 2 ‑ Create a machine catalog of the Remote PC Access type

1. In Citrix Studio, right‑click Machine Catalogs and select Create Machine Catalog from the
shortcut menu.

2. Click Next on the Introduction page.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 160

Linux Virtual Delivery Agent 1912 LTSR

3. Select Remote PC Access on the Operating System page.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 161

Linux Virtual Delivery Agent 1912 LTSR

4. Click Add OUs to select OUs that contain the target PCs, or click Add machine accounts to add
individual machines to the machine catalog.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 162

Linux Virtual Delivery Agent 1912 LTSR

5. Name the machine catalog.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 163

Linux Virtual Delivery Agent 1912 LTSR

6. (Optional) Right‑click the machine catalog to perform relevant operations.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 164

Linux Virtual Delivery Agent 1912 LTSR

Step 3 ‑ Create a Delivery Group to make the PCs in the machine catalog available for users
who request access

1. In Citrix Studio, right‑click Delivery Groups and select Create Delivery Group from the short‑
cut menu.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 165

Linux Virtual Delivery Agent 1912 LTSR

2. Click Next on the Getting started with Delivery Groups page.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 166

Linux Virtual Delivery Agent 1912 LTSR

3. Select the machine catalog created in Step 2 to associate it with the Delivery Group.

4. Add users who can access the PCs in the machine catalog. The users you add can use Citrix
Workspace app on a client device to access the PCs remotely.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 167

Linux Virtual Delivery Agent 1912 LTSR

Considerations

These considerations are specific to the Linux VDA:

• Use the Linux VDA on physical machines only in non‑3D mode. Due to limitations on NVIDIA’s
driver, the local screen of the PC cannot be blacked out and displays the activities of the session
when HDX 3D mode is enabled. Showing this screen is a security risk.

• Use machine catalogs of type single‑session OS for physical Linux machines.

• The integrated Wake on LAN functionality is not available for Linux machines.

• Automatic user assignment is not available for Linux machines. With automatic user assign‑
ment, users are automatically assigned to their machines when they log on locally to the PCs.
This logon occurs without administrator intervention. The Citrix Workspace app running on the
client device gives users access to the applications and data on the office PC within the Remote
PC Access desktop session.

• If users are already logged on to their PCs locally, attempts to launch the PCs from StoreFront
fail.

• Power saving options are not available for Linux machines.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 168

Linux Virtual Delivery Agent 1912 LTSR

More resources

The following are other resources for Remote PC Access:

• Solution design guidance: Remote PC Access Design Decisions.

• Examples of Remote PC Access architectures: Reference Architecture for Citrix Remote PC Ac‑
cess Solution.

Print

June 18, 2020

This article provides information about printing best practices.

Installation

The Linux VDA requires both cups and foomatic filters. The filters are installed when you install the
VDA. You can also install the filters manually based on the distribution. For example:

On RHEL 7:

1 sudo yum – y install cups

2
3 sudo yum -y install foomatic-filters
4 <!--NeedCopy-->

On RHEL 6:

1 sudo yum – y install cups

2
3 sudo yum -y install foomatic
4 <!--NeedCopy-->

Configuration

There are three types of Universal Printer Driver supplied by Citrix (postscript, pcl5, and pcl6). How‑
ever, the Universal Printer Driver might not be compatible with your client printer. In this case, your
only option in earlier releases was to edit the ~/.CtxlpProfile$CLIENT_NAME configuration file. Start‑
ing with Version 1906, you can choose to configure the Printer driver mapping and compatibility
policy in Citrix Studio instead.

To configure the Printer driver mapping and compatibility policy in Citrix Studio:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 169

Linux Virtual Delivery Agent 1912 LTSR

1. Select the Printer driver mapping and compatibility policy.

2. Click Add.

3. Fill in Driver name with the driver name of the client printer. If you are using Citrix Workspace
app for Linux, fill in the printer name instead.

4. Choose Replace with and type in the absolute path of the driver file on the VDA.

Note:

• Only PPD driver files are supported.

• Other options of the Printer driver mapping and compatibility policy are not supported.
Only Replace with takes effect.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 170

Linux Virtual Delivery Agent 1912 LTSR

Usage

You can print from both published desktops and published applications. Only the client‑side default
printer is mapped into a Linux VDA session. The printer names are different for desktops and applica‑
tions:

• For published desktops:

CitrixUniversalPrinter:$CLIENT_NAME:dsk$SESSION_ID

• For published applications:

CitrixUniversalPrinter:$CLIENT_NAME:app$SESSION_ID

Note:

If the same user opens both a published desktop and a published application, both printers are
available to the session. Printing on a desktop printer in a published application session, or print‑
ing on an application printer in a published desktop fails.

Troubleshooting

Unable to print

When printing is not working correctly, check the print daemon, ctxlpmngt, and the CUPs frame‑
work.

The print daemon, ctxlpmngt, is a per‑session process and must be running for the length of the
session. Run the following command to verify that the printing daemon is running. If ctxlpmngt is
not running, manually start ctxlpmngt from a command line.

1 ps – ef | grep ctxlpmngt
2 <!--NeedCopy-->

If printing is still not working, check the CUPS framework. The ctxcups service is used for printer
management and communicates with the Linux CUPS framework. It is a single process per machine
and can be checked by running the following command:

1 service ctxcups status

2 <!--NeedCopy-->

Extra steps for collecting CUPS logs

To collect CUPS logs, run the following commands to configure the CUPS service file. Otherwise, CUPS
logs cannot be recorded in hdx.log:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 171

Linux Virtual Delivery Agent 1912 LTSR

1 sudo service cups stop

2
3 sudo vi /etc/systemd/system/printer.target.wants/cups.service
4
5 PrivateTmp=false
6
7 sudo service cups start
8
9 sudo systemctl daemon-reload
10 <!--NeedCopy-->

Note:

This configuration is made only for collecting the full printing log when an issue arises. Under
normal circumstances, this configuration is not recommended because it breaks CUPS security.

Print output is garbled

An incompatible printer driver can cause garbled output. A per‑user driver configuration is available
and can be configured by editing the ~/.CtxlpProfile$CLIENT_NAME configuration file:

1 [DEFAULT_PRINTER]
2
3 printername=
4
5 model=
6
7 ppdpath=
8
9 drivertype=
10 <!--NeedCopy-->

Important:

The printername is a field containing the name of the current client‑side default printer. It is a
read‑only value. Do not edit it.

The fields ppdpath, model, and drivertype cannot be set at the same time because only one
takes effect for the mapped printer.

• If the Universal Printer driver is not compatible with the client printer, configure the model of
the native printer driver using the model= option. You can find the current model name of the
printer by using the lpinfo command:

1 lpinfo – m
2
3 …
4
5 xerox/ph3115.ppd.gz Xerox Phaser 3115, SpliX V. 2.0.0

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 172

Linux Virtual Delivery Agent 1912 LTSR

6
7 xerox/ph3115fr.ppd.gz Xerox Phaser 3115, SpliX V. 2.0.0
8 xerox/ph3115pt.ppd.gz Xerox Phaser 3115, SpliX V. 2.0.0
9
10 <!--NeedCopy-->

You can then set the model to match the printer:

1 model=xerox/ph3115.ppd.gz
2 <!--NeedCopy-->

• If the Universal Printer driver is not compatible with the client printer, configure the PPD file
path of the native printer driver. The value of ppdpath is the absolute path of the native printer
driver file.

For example, there is a ppd driver under /home/tester/NATIVE_PRINTER_DRIVER.ppd:

1 ppdpath=/home/tester/NATIVE_PRINTER_DRIVER.ppd
2 <!--NeedCopy-->

• There are three types of Universal Printer Driver supplied by Citrix (postscript, pcl5, and pcl6).
You can configure the driver type based on your printer properties.

For example, if the client default printer driver type is PCL5, set drivertype to:

1 drivertype=pcl5
2 <!--NeedCopy-->

Output size is zero

Try different types of printers. And try a virtual printer like CutePDF and PDFCreator to find out
whether this issue is related to the printer driver.

The print job depends on the printer driver of the client default printer. It’s important to identify the
type of the current active driver type. If the client printer is using a PCL5 driver but the Linux VDA
chooses a Postscript driver, an issue can occur.

If the printer driver type is correct, you can identify the problem by performing the following steps:

1. Log on to a published desktop session.

2. Run the vi ~/.CtxlpProfile$CLIENT_NAME command.

3. Add the following field to save the spool file on the Linux VDA:

1 deletespoolfile=no
2 <!--NeedCopy-->

4. Log off and back on to load the configuration changes.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 173

Linux Virtual Delivery Agent 1912 LTSR

5. Print the document to reproduce the issue. After printing, a spool file is saved under
/var/spool/cups‑ctx/$logon_user/$spool_file.

6. Check whether the spool is empty. If the spool file is zero, it represents an issue. Contact Citrix
Support (and provide the printing log) for more guidance.

7. If the spool size is not zero, copy the file to the client. The spool file content depends on the
printer driver type of the client default printer. If the mapped printer (native) driver is postscript,
the spool file can be opened in the Linux OS directly. Check whether the content is correct.

If the spool file is PCL, or if the client OS is Windows, copy the spool file to the client and print it
on the client‑side printer by using a different printer driver.

8. Change the mapped printer to use a different printer driver. The following example uses the
postscript client printer as an example:

a) Log on to an active session and open a browser on the client desktop.

b) Open the printing management portal:

1 localhost:631
2 <!--NeedCopy-->

c) Choose the mapped printer CitrixUniversalPrinter:$ClientName:app/dsk$SESSION_ID

and Modify Printer. This operation requires administrator privileges.

d) Retain the cups‑ctx connection, then click Continue to change the printer driver.

e) In the Make and Model fields, choose a different printer driver from the Citrix UPD dri‑
ver. For example, if the CUPS‑PDF virtual printer is installed, select the Generic CUPS‑PDF
Printer driver. Save the change.

f) If this process succeeds, configure the PPD file path of the driver in .CtxlpPro‑
file$CLIENT_NAME to allow the mapped printer to use the newly selected driver.

Known issues

The following issues have been identified during printing on the Linux VDA:

CTXPS driver is not compatible with some PLC printers

If you encounter printing output corruption, set the printer driver to the native one provided by the
manufacturer.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 174

Linux Virtual Delivery Agent 1912 LTSR

Slow printing performance for large documents

When you print a large document on a local client printer, the document is transferred over the server
connection. On slow connections, the transfer can take a long time.

Printer and print job notifications seen from other sessions

Linux does not have the same session concept as the Windows operating system. Therefore, all users
get system‑wide notifications. You can disable these notifications by changing the CUPS configuration
file: /etc/cups/cupsd.conf.

Locate the current policy name configured in the file:

DefaultPolicy default

If the policy name is default, add the following lines to the default policy XML block:

1 <Policy default>
2
3 # Job/subscription privacy...
4
5 JobPrivateAccess default
6
7 JobPrivateValues default
8
9 SubscriptionPrivateAccess default
10
11 SubscriptionPrivateValues default
12
13 … …
14
15 <Limit Create-Printer-Subscription>
16
17 Require user @OWNER
18
19 Order deny,allow
20
21 </Limit>
22
23 <Limit All>
24
25 Order deny,allow
26
27 </Limit>
28
29 </Policy>
30 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 175

Linux Virtual Delivery Agent 1912 LTSR

File transfer

May 20, 2020

File transfer is supported between the Linux VDA and the client device. This feature is available when
the client device runs a web browser that supports the HTML5 sandbox attribute. The HTML5 sandbox
attribute allows users to access virtual apps and desktops using Citrix Workspace app for HTML5 and
for Chrome. Within published sessions, you can use the toolbar of Citrix Workspace app to upload and
download files between the Linux VDA and the client device. For example, you can click the Upload
icon on the toolbar, choose a file on the client device, and upload the file to the Linux VDA.

Note:

This feature is available for RedHat7.7, CentOS7.6, SUSE12.3, Ubuntu16.04, and Ubuntu18.04.
To use this feature, ensure that the toolbar of Citrix Workspace app is enabled.

File transfer policies

You can use Citrix Studio to set the file transfer policies. By default, file transfer is enabled.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 176

Linux Virtual Delivery Agent 1912 LTSR

Policy descriptions:

• Allow file transfer between desktop and client. Allows or prevents users from transferring
files between a Citrix Virtual Apps and Desktops session and their devices.

• Download file from desktop. Allows or prevents users from downloading files from a Citrix
Virtual Apps and Desktops session to their device.

• Upload file to desktop. Allows or prevents users from uploading files from their device to a
Citrix Virtual Apps and Desktops session.

Note:

To ensure that the Download file from desktop and Upload file to desktop policies take effect,
set the Allow file transfer between desktop and client policy to Allowed.

Usage

To use the file transfer feature through Citrix Workspace app for HTML5:

1. In Citrix Studio, set the WebSockets connections policy to Allowed.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 177

Linux Virtual Delivery Agent 1912 LTSR

2. In Citrix Studio, enable file transfer through the file transfer policies described earlier.

3. In the Citrix StoreFront management console, click Stores, select the Manage Receiver for
Web Sites node, and enable Citrix Receiver for HTML5 by selecting the Always use Receiver
for HTML5 option.

4. Launch a virtual desktop or web browser app session. Upload and download files between the
Linux VDA and your client device.

To use the file transfer feature through Citrix Workspace app for Chrome:

1. Enable file transfer through the file transfer policies described earlier.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 178

Linux Virtual Delivery Agent 1912 LTSR

2. Obtain Citrix Workspace app from the Chrome Web Store.

Skip this step if you already added Citrix Workspace app for Chrome to the Chrome Apps page.

a) Type Citrix Workspace for Chrome in the search box of Google Chrome. Click the search
icon.

b) Among the search results, click the URL to the Chrome Web Store where Citrix Workspace
app is available.

c) Click Add to Chrome to add Citrix Workspace app to Google Chrome.

3. Click Citrix Workspace app for Chrome on the Chrome Apps page.

4. Type the URL of your StoreFront store to connect.

Skip this step if you typed the URL before.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 179

Linux Virtual Delivery Agent 1912 LTSR

5. Launch a virtual desktop or web browser app session. Upload and download files between the
Linux VDA and your client device.

PDF printing

April 29, 2020

Using a version of Citrix Workspace app that supports PDF printing, you can print PDFs converted from
within the Linux VDA sessions. Session print jobs are sent to the local machine where Citrix Workspace
app is installed. On the local machine, you can open PDFs using your PDF viewer of choice and print
them on your printer of choice.

The Linux VDA supports PDF printing on the following versions of Citrix Workspace app:

• Citrix Receiver for HTML5 Versions 2.4 through 2.6.9, Citrix Workspace app 1808 for HTML5 and
later
• Citrix Receiver for Chrome Versions 2.4 through 2.6.9, Citrix Workspace app 1808 for Chrome
and later

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 180

Linux Virtual Delivery Agent 1912 LTSR

• Citrix Workspace app 1905 for Windows and later

Configuration

Apart from using a version of Citrix Workspace app that supports PDF printing, enable the following
policies in Citrix Studio:

• Client Printer Redirection (enabled by default)

• Auto‑create PDF Universal Printer (disabled by default)

With these policies enabled, a print preview appears on the local machine for you to select a printer
when you click Print within your launched session. See the Citrix Workspace app documentation for
information about setting default printers.

Configure graphics

February 21, 2023

This article provides guidance for the Linux VDA graphics configuration and fine‑tuning.

For more information, see System requirements and the Installation overview section.

Configuration

Thinwire is the display remoting technology used in the Linux VDA. The technology allows graphics
generated on one machine to be transmitted, typically across a network, to another machine for dis‑
play.

The Use video codec for compression graphics policy sets the default graphics mode and provides
the following options for different use cases:

• Use when preferred. This setting is the default. No additional configuration is required. Keep‑
ing this setting ensures that Thinwire is selected for all Citrix connections, and optimized for
scalability, bandwidth, and superior image quality for typical desktop workloads.
• For the entire screen. Delivers Thinwire with full‑screen H.264 or H.265 to optimize for im‑
proved user experience and bandwidth, especially in cases with heavy use of 3D graphics.
• For actively changing regions. The adaptive display technology in Thinwire identifies moving
images (video, 3D in motion), and uses H.264 only in the part of the screen where the image is
moving. The selective use of the H.264 video codec enables HDX Thinwire to detect and en‑
code parts of the screen that are frequently updated using the H.264 video codec, for example,

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 181

Linux Virtual Delivery Agent 1912 LTSR

video content. Still image compression (JPEG, RLE) and bitmap caching continue to be used
for the rest of the screen, including text and photographic imagery. Users get the benefit of
lower bandwidth and better quality for video content combined with lossless text or high qual‑
ity imagery elsewhere. To enable this feature, change the policy setting Use video codec for
compression to Use when preferred (default) or For actively changing regions. For more
information, see Graphics policy settings.

Some other policy settings, including the following visual display policy settings can be used to fine‑
tune the performance of display remoting:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 182

Linux Virtual Delivery Agent 1912 LTSR

• Preferred color depth for simple graphics

• Target frame rate
• Visual quality

Use H.264 for Build to Lossless in Thinwire

By default, the Build to Lossless preference of the Visual quality policy setting is now H.264 instead
of JPEG for moving images.

H.264 encoding offers superior image quality. The Use video codec for compression policy controls
that preference, with the default being Use when preferred. To force Build to Lossless to use JPEG,
set the Use video codec for compression policy to Do not use video codec. If your client does not
support Selective H.264, Build to Lossless falls back to JPEG regardless of the policy settings. Citrix
Receiver for Windows 4.9 through 4.12, Citrix Receiver for Linux 13.5 through 13.10, Citrix Workspace
app 1808 for Windows and later, and Citrix Workspace app 1808 for Linux and later support Selective
H.264. For more information about the Visual quality and Use video codec for compression policy
settings, see Visual display policy settings and Graphics policy settings.

Support for H.265 video codec

Starting with the 7.18 release, the Linux VDA supports the H.265 video codec for hardware acceleration
of remote graphics and videos. You can use this feature on Citrix Receiver for Windows 4.10 through
4.12 and on Citrix Workspace app 1808 for Windows and later. To benefit from this feature, enable it
on both the Linux VDA and on your client. If the GPU of your client does not support H.265 decoding
using the DXVA interface, the H.265 Decoding for graphics policy setting is ignored and the session
falls back to using the H.264 video codec. For more information, see H.265 video encoding.

To enable H.265 hardware encoding on the VDA:

1. Enable the Use hardware encoding for video codec policy.

2. Enable the Optimize for 3D graphics workload policy
3. Ensure that the Use video codec for compression policy is default or set to For the entire
screen.
4. Ensure that the Visual quality policy is NOT set to Build to Lossless or Always Lossless.

To enable H.265 hardware encoding on your client, see H.265 video encoding.

Support for YUV444 software encoding

The Linux VDA supports YUV444 software encoding. The YUV encoding scheme assigns both bright‑
ness and color values to each pixel. In YUV, ‘Y’represents the brightness or ‘luma’value, and ‘UV’

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 183

Linux Virtual Delivery Agent 1912 LTSR

represents the color or ‘chroma’values. You can use this feature of the Linux VDA on Citrix Receiver
for Windows 4.10 through 4.12 and on Citrix Workspace app 1808 for Windows and later.

Each unique Y, U, and V value comprises 8 bits, or one byte, of data. The YUV444 data format transmits
24 bits per pixel. The YUV422 data format shares U and V values between two pixels, which results in
an average transmission rate of 16 bits per pixel. The following table shows an intuitive comparison
between YUV444 and YUV420.

YUV444 YUV420

To enable YUV444 software encoding on the VDA:

1. Ensure that the Use video codec for compression policy is set to For the entire screen.
2. Ensure that the Visual quality policy is set to Always Lossless or Build to Lossless.

Adjust average bit rates based on bandwidth estimates

Citrix enhances HDX 3D Pro hardware encoding by adjusting average bit rates based on bandwidth
estimates.

When the HDX 3D Pro hardware encoding is in use, the VDA can intermittently estimate the bandwidth
of the network and adjust the bit rates of encoded frames based on the bandwidth estimates. This new
feature provides a mechanism to balance between sharpness and fluency.

This feature is enabled by default. To disable it, run the following command:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
DisableReconfigureEncoder" -d "0x00000001" --force
2 <!--NeedCopy-->

In addition to using this feature, you can also run the following commands to adjust between sharp‑
ness and fluency. The AverageBitRatePercent and MaxBitRatePercent parameters set the percent‑
age of bandwidth usage. The higher values you set, the sharper graphics and lower fluency you get.
The recommended setting range is 50–100.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 184

Linux Virtual Delivery Agent 1912 LTSR

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
AverageBitRatePercent" -d "90" --force
2
3 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\
CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
MaxBitRatePercent" -d "100" --force
4 <!--NeedCopy-->

In the average bit rate adjustment, when your screen holds still, the most recent frame stays in a low‑
quality state because no new frames are sent. Sharpening support can address this issue by reconfig‑
uring and immediately sending the most recent frame at the highest quality.

For a full list of the policies supported by the Linux VDA Thinwire, see Policy support list.

For information on the configuration of multi‑monitor support on the Linux VDA, see CTX220128.

Troubleshooting

Check which graphics mode is in use

Run the following command to check which graphics mode is in use (0 means TW+; 1 means full‑
screen video codec):

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep GraphicsMode

2 <!--NeedCopy-->

The result resembles:

create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"

-v "GraphicsMode"-d "0x00000000"--force

Check whether H.264 is in use

Run the following command to check whether H.264 is in use (0 means not in use; 1 means in use):

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep H264

2 <!--NeedCopy-->

The result resembles:

create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"

-v "H264"-d "0x00000000"--force

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 185

Linux Virtual Delivery Agent 1912 LTSR

Check whether H.265 is in use

Run the following command to check whether full‑screen H.265 is in use (0 means not in use; 1 means
in use):

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep H265

2 <!--NeedCopy-->

The result resembles:

create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"

-v "H265"-d "0x00000000"--force

Check which YUV encoding scheme is in use

Run the following command to check which YUV encoding scheme is in use (0 means YUV420. 1 means
YUV422. 2 means YUV444):

Note: The value of YUVFormat is meaningful only when a video codec is in use.

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep YUVFormat

2 <!--NeedCopy-->

The result resembles:

create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"

-v "YUVFormat"-d "0x00000000"--force

Check whether YUV444 software encoding is in use

Run the following command to check whether YUV444 software encoding is in use:

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep Graphics

2 <!--NeedCopy-->

When YUV444 is in use, the result resembles:

create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"

-v "GraphicsMode"-d "0x00000001"--force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"
-v "H264"-d "0x00000001"--force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"
-v "HardwareEncoding"-d "0x00000000"--force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics"-t "REG_DWORD"
-v "YUVFormat"-d "0x00000002"--force

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 186

Linux Virtual Delivery Agent 1912 LTSR

Check whether hardware encoding is in use for 3D Pro

Run the following command (0 means not in use; 1 means in use):

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep HardwareEncoding

2 <!--NeedCopy-->

The results resemble:

create -k "HKLM\Software\Citrix\Ica\Session\1\Graphics"-t "REG_DWORD"

-v "HardwareEncoding"-d "0x00000001"--force

Another way is to use the nvidia‑smi command. The outputs resemble the following if hardware en‑
coding is in use:

1 Tue Apr 12 10:42:03 2016

2 +------------------------------------------------------+
3 | NVIDIA-SMI 361.28 Driver Version: 361.28 |
4 |-------------------------------+----------------------+----------------------+

5 | GPU Name Persistence-M| Bus-Id Disp.A | Volatile

Uncorr. ECC |
6 | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util
Compute M. |
7 |===============================+======================+======================|

8 | 0 GRID K1 Off | 0000:00:05.0 Off |

N/A |
9 | N/A 42C P0 14W /
31W | 207MiB / 4095MiB | 8%
Default |
10 +-------------------------------+----------------------+----------------------+

11
12 +-----------------------------------------------------------------------------+

13 | Processes: GPU
Memory |
14 | GPU PID Type Process name
Usage |
15 |=============================================================================|

16 | 0 2164 C+G /usr/local/bin/ctxgfx

106MiB |
17 | 0 2187 G Xorg
85MiB |
18 +-----------------------------------------------------------------------------+

19 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 187

Linux Virtual Delivery Agent 1912 LTSR

Verify that the NVIDIA GRID graphics driver is installed correctly

To verify that the NVIDIA GRID graphics driver is installed correctly, run nvidia‑smi. The results resem‑
ble:

1 +------------------------------------------------------+
2 | NVIDIA-SMI 352.70 Driver Version: 352.70 |
3 |-------------------------------+----------------------+----------------------+

4 | GPU Name Persistence-M| Bus-Id Disp.A | Volatile

Uncorr. ECC |
5 | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util
Compute M. |
6 |===============================+======================+======================|

7 | 0 Tesla M60 Off | 0000:00:05.0 Off |

Off |
8 | N/A 20C P0 37W / 150W | 19MiB / 8191MiB |0%
Default |
9 +-------------------------------+----------------------+----------------------+

10
11 +-----------------------------------------------------------------------------+

12 | Processes: GPU
Memory |
13 | GPU PID Type Process name
Usage |
14 |=============================================================================|

15 | No running processes found

|
16 +-----------------------------------------------------------------------------+

17 <!--NeedCopy-->

Set the correct configuration for the card:

etc/X11/ctx-nvidia.sh

HDX 3D Pro multi‑monitor redraw issues

If you are seeing redraw issues on screens other than the primary monitor, check that the NVIDIA GRID
license is available.

Check Xorg error logs

The log file of Xorg is named similar to Xorg.{DISPLAY}.log in the /var/log/ folder.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 188

Linux Virtual Delivery Agent 1912 LTSR

Known issues and limitations

For vGPU, the Citrix Hypervisor local console shows the ICA desktop session screen

Workaround: Disable the VM’s local VGA console by running the following commands:

For Citrix Hypervisor 8.1 and later:

1 [root@xenserver ~]# xe vgpu-param-set uuid=vgpu-uuid extra_args=

disable_vnc=1
2 <!--NeedCopy-->

For Citrix Hypervisor earlier than 8.1:

1 xe vm-param-set uuid=<vm-uuid> platform:vgpu_extra_args="disable_vnc=1"

2 <!--NeedCopy-->

NVIDIA K2 graphics cards do not support YUV444 hardware encoding in pass‑through mode

With Build to Lossless enabled through the policy setting, a black or gray screen appears when users
are launching an app/desktop session with an NVIDIA K2 graphics card. The issue occurs because
NVIDIA K2 graphics cards do not support YUV444 hardware encoding in pass‑through mode. For more
information, see Video Encode and Decode GPU Support Matrix.

Gnome 3 desktop popups slow when logging on

It is a limitation of Gnome 3 desktop session startup.

Some OpenGL/WebGL applications do not render well upon resizing the Citrix Workspace app
window

Resizing the window of Citrix Workspace app changes the screen resolution. The NVIDIA proprietary
driver changes some internal states and might require applications to respond accordingly. For exam‑
ple, the WebGL library element lightgl.js might spawn an error saying that ‘Rendering to this
texture is not supported (incomplete frame buffer)’.

Thinwire progressive display

June 18, 2020

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 189

Linux Virtual Delivery Agent 1912 LTSR

Session interactivity can degrade on low bandwidth or high latency connections. For example, on
connections with less than 2 Mbps bandwidth or latency of more than 200 ms, scrolling on a webpage
can become slow, unresponsive, or choppy. Keyboard and mouse operations can lag behind graphics
updates.

Through version 7.17, you were able to use policy settings to reduce bandwidth consumption by con‑
figuring the session to Low visual quality, or setting a lower color depth (16‑bit or 8‑bit graphics). How‑
ever, you had to know that a user was on a weak connection. HDX Thinwire did not dynamically adjust
static image quality based on network conditions.

Starting with Version 7.18, HDX Thinwire, by default, switches to a progressive update mode when
available bandwidth falls below 2 Mbps, or network latency exceeds 200 ms. In this mode:

• All static images are heavily compressed.

• Text quality is reduced.

For example, in the following graphic where progressive update mode is active, the letters F and e have
blue artifacts, and the image is heavily compressed. This approach significantly reduces bandwidth
consumption, which allows images and text to be received more quickly, and session interactivity
improves.

When you stop interacting with the session, the degraded images and text are progressively sharpened
to lossless. For example, in the following graphic, the letters no longer contain blue artifacts, and the
image appears at source quality.

For images, sharpening uses a random block‑like method. For text, individual letters or parts of words

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 190

Linux Virtual Delivery Agent 1912 LTSR

are sharpened. The sharpening process occurs over several frames. This approach avoids introducing
a delay with a single large sharpening frame.

Transient imagery (video) is still managed with adaptive display or Selective H.264.

How progressive mode is used

By default, progressive mode is on standby for the Visual quality policy settings: High, Medium (de‑
fault), and Low.

Progressive mode is forced off (not used) when:

• Visual quality = Always Lossless or Build to Lossless

• Preferred color depth for simple graphics = 8‑bit
• Use video codec for compression = For the entire screen (when full‑screen H.264 is desired)

When progressive mode is on standby, by default it is enabled when either of the following conditions
occurs:

• Available bandwidth drops below 2 Mbps

• Network latency increases above 200 ms

After a mode switch occurs, a minimum of 10 s is spent in that mode, even if the adverse network
conditions are momentary.

Change progressive mode behavior

You can change the progressive mode behavior by running the following command:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SOFTWARE\

CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
ProgressiveDisplay" -d "<value>" --force
2 <!--NeedCopy-->

where <value>:

0 = Always off (do not use under any circumstances)

1 = Automatic (toggle based on network conditions, default value)

2 = Always on

When in automatic mode (1), you can run either of the following commands to change the thresholds
at which progressive mode is toggled:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
ProgressiveDisplayBandwidthThreshold" -d "<value>" --force

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 191

Linux Virtual Delivery Agent 1912 LTSR

2 <!--NeedCopy-->

where <value> is <threshold in Kbps> (default = 2,048)

Example: 4096 = toggle progressive mode on if bandwidth falls below 4 Mbps

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SOFTWARE

\CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "
ProgressiveDisplayLatencyThreshold" -d "<value>" --force
2 <!--NeedCopy-->

where <value> is <threshold in ms> (default = 200)

Example: 100 = toggle progressive mode on if network latency drops below 100 ms.

Non‑GRID 3D graphics

February 20, 2024

Overview

With this feature enhancement, the Linux VDA supports not only NVIDIA GRID 3D cards but also non‑
GRID 3D cards.

Installation

To use the non‑GRID 3D graphics feature, you must:

• Install XDamage as a prerequisite. Typically, XDamage exists as an extension of XServer.

• Set CTX_XDL_HDX_3D_PRO to Y when installing the Linux VDA. For information about envi‑
ronment variables, see Step 7: Set up the runtime environment to complete the installation.

Configuration

Xorg configuration files

If your 3D card driver is NVIDIA, the configuration files are installed and set automatically.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 192

Linux Virtual Delivery Agent 1912 LTSR

Other types of 3D cards

If your 3D card driver is NOT NVIDIA, you must modify the four template configuration files installed
under /etc/X11/:

• ctx‑driver_name‑1.conf
• ctx‑driver_name‑2.conf
• ctx‑driver_name‑3.conf
• ctx‑driver_name‑4.conf

Using ctx‑driver_name‑1.conf as an example, do the following to modify the template configuration

files:

1. Replace driver_name with your actual driver name.

For example, if your driver name is intel, you can change the configuration file name to ctx
-intel-1.conf.

2. Add the video driver information.

Each template configuration file contains a section named “Device,”which is commented out.
This section describes the video driver information. Enable this section before adding your
video driver information. To enable this section:

a) See the 3D card guide provided by the manufacturer for configuration information. A na‑
tive configuration file can be generated. Verify that your 3D card can work in a local envi‑
ronment with the native configuration file when you are not using a Linux VDA ICA session.

b) Copy the “Device”section of the native configuration file to ctx‑driver_name‑1.conf.

3. Run the following command to set the registry key so that the Linux VDA can recognize the con‑
figuration file name set in Step 1.

1 /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\XDamage" -t "REG_SZ" -v "
DriverName" -d "intel" --force
2 <!--NeedCopy-->

Enable the non‑GRID 3D graphics feature

The non‑GRID 3D graphics feature is disabled by default. You can run the following command to en‑
able it by setting XDamageEnabled to 1.

1 /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\XDamage" -t "REG_DWORD" -v "
XDamageEnabled" -d "0x00000001" --force
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 193

Linux Virtual Delivery Agent 1912 LTSR

Troubleshooting

No or garbled graphic output

If you can run 3D applications locally and all configurations are correct, missing or garbled graphic
output is the result of a bug. Use /opt/Citrix/VDA/bin/setlog and set GFX_X11 to verbose to collect the
trace information for debugging.

Hardware encoding does not work

This feature supports only software encoding.

Configure policies

June 18, 2020

Installation

Follow the installation articles to prepare the Linux VDA.

Dependencies

Ensure that you install these dependencies before installing the Linux VDA package.

RHEL/CentOS:

1 sudo yum -y install openldap

2
3 sudo yum -y install libxml2
4
5 sudo yum -y install cyrus-sasl
6
7 sudo yum -y install cyrus-sasl-gssapi
8 <!--NeedCopy-->

SLES/SELD:

1 sudo zypper install openldap2

2
3 sudo zypper install libxml2
4
5 sudo zypper install cyrus-sasl

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 194

Linux Virtual Delivery Agent 1912 LTSR

6
7 sudo zypper install cyrus-sasl-gssapi
8 <!--NeedCopy-->

Ubuntu:

1 sudo apt-get install -y libldap-2.4-2

2
3 sudo apt-get install -y libsasl2-2
4
5 sudo apt-get install -y libsasl2-modules-gssapi-mit
6 <!--NeedCopy-->

Configuration

Policy settings in Citrix Studio

To set policies in Citrix Studio, do the following:

1. Open Citrix Studio.

2. Select the Policies panel.
3. Click Create Policy.
4. Set the policy according to the Policy support list.

LDAP server setting on the VDA

The LDAP server setting on Linux VDA is optional for single domain environments but mandatory for
multiple domain and multiple forest environments. This setting is necessary for the policy service to
perform an LDAP search in these environments.

After installing the Linux VDA package, run the command:

1 /opt/Citrix/VDA/sbin/ctxsetup.sh
2 <!--NeedCopy-->

Type all the LDAP servers in the suggested format: space‑separated list of LDAP Fully Qual‑
ified Domain Names (FQDNs) with the LDAP port (for example, ad1.mycompany.com:389
ad2.mycomany.com:389).

You can also run the ctxreg command to write this setting to the registry directly:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 195

Linux Virtual Delivery Agent 1912 LTSR

1 /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\

VirtualDesktopAgent" -t "REG_SZ" -v "ListOfLDAPServers" -d "ad1.
mycompany.com:389 ad2.mycomany.com:389" --force
2 <!--NeedCopy-->

Policy support list

December 16, 2020

Linux VDA policy support list

Studio Policy Key Name Type Module Default Value

Use local time of UseLocalTimeOfClient

User ICA\Time Zone Use server time
client Control zone
ICA round trip IcaRoundTripCheckEnabled
Computer ICA\End User Enabled (1)
calculation Monitoring
ICA round trip IcaRoundTripCheckPeriod
Computer ICA\End User 15
calculation Monitoring
interval
ICA round trip IcaRoundTripCheckWhenIdle
Computer ICA\End User Disabled (0)
calculations for Monitoring
idle connections
Overall session LimitOverallBw User ICA\Bandwidth 0
bandwidth limit
Audio redirection LimitAudioBw User ICA\Bandwidth 0
bandwidth limit
Audio redirection LimitAudioBwPercent
User ICA\Bandwidth 0
bandwidth limit
percent
Client USB device LimitUSBBw User ICA\Bandwidth 0
redirection
bandwidth limit
Client USB device LimitUSBBwPercent User ICA\Bandwidth 0
redirection
bandwidth
percent

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 196

Linux Virtual Delivery Agent 1912 LTSR

Studio Policy Key Name Type Module Default Value

Clipboard LimitClipbdBW User ICA\Bandwidth 0

redirection
bandwidth limit
Clipboard LimitClipbdBWPercent
User ICA\Bandwidth 0
redirection
bandwidth limit
percent
File redirection LimitCdmBw User ICA\Bandwidth 0
bandwidth limit
File redirection LimitCdmBwPercentUser ICA\Bandwidth 0
bandwidth limit
percent
Printer LimitPrinterBw User ICA\Bandwidth 0
redirection
bandwidth limit
Printer LimitPrinterBwPercent
User ICA\Bandwidth 0
redirection
bandwidth limit
percent
WebSockets AcceptWebSocketsConnections
Computer ICA\WebSockets Prohibited
connections
WebSockets port WebSocketsPort Computer ICA\WebSockets 8008
number
WebSockets WSTrustedOriginServerList
Computer ICA\WebSockets *
trusted origin
server list
ICA keep alives SendICAKeepAlives Computer ICA keep alive Do not send ICA
keep alive
messages (0)
ICA keep alive ICAKeepAliveTimeoutComputer ICA keep alive 60 seconds
timeout
ICA listener port IcaListenerPortNumber
Computer ICA 1494
number
HDX adaptive HDXoverUDP Computer ICA Preferred(2)
transport
Session reliability AcceptSessionReliabilityConnections
Computer ICA\Session Allowed(1)
connections Reliability

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 197

Linux Virtual Delivery Agent 1912 LTSR

Studio Policy Key Name Type Module Default Value

Reconnection UI ReconnectionUiTransparencyLevel
Computer ICA\Auto Client 80%
transparency Reconnect
level
Session reliability SessionReliabilityPort
Computer ICA\Session 2598
port number Reliability
Session reliability SessionReliabilityTimeout
Computer ICA\Session 180s
timeout Reliability
Auto Client AllowAutoClientReconnect
User ICA\Auto Client Allowed (1)
Reconnect Reconnect
Client audio AllowAudioRedirection
User Audio Allowed (1)
redirection
Client printer AllowPrinterRedir User Printing Allowed (1)
redirection
Auto‑create PDF AutoCreatePDFPrinter
User Printing Disabled (0)
Universal Printer
Printer driver DriverMappingList User Printing "Microsoft
mapping and XPS Document
compatibility Writer *,
Deny;Send to
Microsoft
OneNote *,
Deny"
Client clipboard AllowClipboardRedirUser Clipboard Allowed (1)
redirection
Client USB device AllowUSBRedir User USB Prohibited (0)
redirection
Client USB device USBDeviceRules User USB “\0”
redirection rules
Moving image MovingImageCompressionConfiguration
User Thinwire Enabled (1)
compression
Extra color ExtraColorCompression
User Thinwire Disabled (0)
compression
Target minimum TargetedMinimumFramesPerSecond
User Thinwire 10 fps
frame rate
Target frame rate FramesPerSecond User Thinwire 30 fps
Visual quality VisualQuality User Thinwire Medium (3)

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 198

Linux Virtual Delivery Agent 1912 LTSR

Studio Policy Key Name Type Module Default Value

Use video codec VideoCodec User Thinwire Use when

for compression preferred (3)
Use hardware UseHardwareEncodingForVideoCodec
User Thinwire Enabled (1)
encoding for
video codec
Allow visually AllowVisuallyLosslessCompression
User Thinwire Disabled (0)
lossless
compression
Optimize for 3D OptimizeFor3dWorkload
User Thinwire Disabled (0)
graphics
workload
Preferred color PreferredColorDepthUser Thinwire 24 bits per
depth for simple pixel(1)
graphics
Audio quality SoundQuality User Audio High –high
definition audio
(2)
Client AllowMicrophoneRedir
User Audio Allowed (1)
microphone
redirection
Maximum MaximumNumberOfSessions
Computer Load 250
number of Management
sessions
Concurrent ConcurrentLogonsTolerance
Computer Load 2
logons tolerance Management
Enable auto EnableAutoUpdateOfControllers
Computer Virtual Delivery Allowed (1)
update of Agent Settings
Controllers
Clipboard ClipboardSelectionUpdateMode
User Clipboard 3
selection update
mode
Primary selection PrimarySelectionUpdateMode
User Clipboard 3
update mode
Max speex quality MaxSpeexQuality User Audio 5
Auto connect AutoConnectDrives User File Enabled (1)
client drives redirection/CDM

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 199

Linux Virtual Delivery Agent 1912 LTSR

Studio Policy Key Name Type Module Default Value

Client optical AllowCdromDrives User File Allowed (1)

drives redirection/CDM
Client fixed drives AllowFixedDrives User File Allowed (1)
redirection/CDM
Client floppy AllowFloppyDrives User File Allowed (1)
drives redirection/CDM
Client network AllowNetworkDrivesUser File Allowed (1)
drives redirection/CDM
Client drive AllowDriveRedir User File Allowed (1)
redirection redirection/CDM
Read‑only client ReadOnlyMappedDrive
User File Disabled (0)
drive access redirection/CDM
Automatic AllowAutoKeyboardPopUp
User MRVC Disabled (0)
keyboard display
Allow file transfer AllowFileTransfer User File Transfer Allowed
between desktop
and client
Download file AllowFileDownload User File Transfer Allowed
from desktop
Upload file to AllowFileUpload User File Transfer Allowed
desktop

The following policies can be configured in Citrix Studio Version 7.12 and later.

• MaxSpeexQuality

Value (integer): [0–10]

Default value: 5

Details:

Audio redirection encodes audio data with the Speex codec when audio quality is medium or
low (see the policy Audio quality). Speex is a lossy codec, which means that it achieves compres‑
sion at the expense of fidelity of the input speech signal. Unlike some other speech codecs, it is
possible to control the tradeoff made between quality and bit rate. The Speex encoding process
is controlled most of the time by a quality parameter that ranges from 0 to 10. The higher the
quality is, the higher the bit rate.

The max Speex quality chooses the best Speex quality to encode audio data according to audio
quality and bandwidth limit (see the policy Audio redirection bandwidth limit). If the audio

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 200

Linux Virtual Delivery Agent 1912 LTSR

quality is medium, the encoder is in wide band mode, which means a higher sampling rate. If
the audio quality is low, the encoder is in narrow band mode, which means a lower sampling
rate. The same Speex quality has different bit rates in different modes. The best Speex quality
is when the largest value meets the following conditions:

– It is equal to or less than the max Speex quality.

– Its bit rate is equal to or less than the bandwidth limit.

Related Settings: Audio quality, Audio redirection bandwidth limit

• PrimarySelectionUpdateMode

Value (enum): [0, 1, 2, 3]

Default value: 3

Details:

Primary selection is used when you select data and paste it by pressing the middle mouse but‑
ton.

This policy controls whether primary selection changes on the Linux VDA and client can update
the clipboard on each other. There are four value options:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 201

Linux Virtual Delivery Agent 1912 LTSR

– Selection changes are not updated on neither client nor host

Primary selection changes on the Linux VDA do not update the clipboard on the client.
Primary selection changes on the client do not update the clipboard on the Linux VDA.
– Host selection changes are not updated to client
Primary selection changes on the Linux VDA do not update the clipboard on the client.
Primary selection changes on the client update the clipboard on the Linux VDA.
– Client selection changes are not updated to host
Primary selection changes on the Linux VDA update the clipboard on the client. Primary
selection changes on the client do not update the clipboard on the Linux VDA.
– Selection changes are updated on both client and host
Primary selection changes on the Linux VDA update the clipboard on the client. Primary
selection changes on the client update the clipboard on the Linux VDA. This option is the

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 202

Linux Virtual Delivery Agent 1912 LTSR

default value.

Related Setting: Clipboard selection update mode

• ClipboardSelectionUpdateMode

Value (enum): [0, 1, 2, 3]

Default value: 3

Details:

Clipboard selection is used when you select some data and explicitly request it to be “copied”
to the clipboard, such as by selecting “Copy”from the shortcut menu. Clipboard selection is
primarily used in connection with Microsoft Windows clipboard operations while primary selec‑
tion is unique to Linux.

This policy controls whether clipboard selection changes on the Linux VDA and client can update
the clipboard on each other. There are four value options:

– Selection changes are not updated on neither client nor host

Clipboard selection changes on the Linux VDA do not update the clipboard on the client.
Clipboard selection changes on the client do not update the clipboard on the Linux VDA.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 203

Linux Virtual Delivery Agent 1912 LTSR

– Host selection changes are not updated to client

Clipboard selection changes on the Linux VDA do not update the clipboard on the client.
Clipboard selection changes on the client update the clipboard on the Linux VDA.

– Client selection changes are not updated to host

Clipboard selection changes on the Linux VDA update the clipboard on the client. Clip‑
board selection changes on the client do not update the clipboard on the Linux VDA.

– Selection changes are updated on both client and host

Clipboard selection changes on the Linux VDA update the clipboard on the client. Clip‑
board selection changes on the client update the clipboard on the Linux VDA. This option
is the default value.

Related Setting: Primary selection update mode

Note:

The Linux VDA supports both clipboard selection and primary selection. To control the copy and
paste behaviors between the Linux VDA and the client, Citrix recommends that you set both clip‑
board selection update mode and primary selection update mode to the same value.

Configure IPv6

April 29, 2020

The Linux VDA supports IPv6 to align with Citrix Virtual Apps and Desktops. When using this feature,
consider the following:

• For dual stack environments, IPv4 is used unless IPv6 is explicitly enabled.
• If IPv6 is enabled in an IPv4 environment, the Linux VDA fails to function.

Important:

• The whole network environment must be IPv6, not only for the Linux VDA.
• Centrify does not support pure IPv6.

No special setup tasks are required for IPv6 when you install the Linux VDA.

Configure IPv6 for the Linux VDA

Before changing the configuration for the Linux VDA, ensure that your Linux virtual machine has pre‑
viously worked in an IPv6 network. There are two registry keys related to IPv6 configuration:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 204

Linux Virtual Delivery Agent 1912 LTSR

1 “ HKLM\Software\Policies\Citrix\VirtualDesktopAgent ” -t “ REG_DWORD ”
-v “ OnlyUseIPv6ControllerRegistration ”
2 “ HKLM\Software\Policies\Citrix\VirtualDesktopAgent ” -t “ REG_DWORD ”
-v “ ControllerRegistrationIPv6Netmask ”
3 <!--NeedCopy-->

OnlyUseIPv6ControllerRegistration must be set to 1 to enable IPv6 on the Linux VDA:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Policies\

Citrix\VirtualDesktopAgent" -t "REG_DWORD" -v "
OnlyUseIPv6ControllerRegistration" -d "0x00000001" --force
2 <!--NeedCopy-->

If the Linux VDA has more than one network interfaces, ControllerRegistrationIPv6Netmask can be
used to specify which one is used for the Linux VDA registration:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Policies\

Citrix\VirtualDesktopAgent" -t "REG_SZ" -v "
ControllerRegistrationIPv6Netmask " -d "{
2 IPv6 netmask }
3 " --force
4 <!--NeedCopy-->

Replace {IPv6 netmask} with the real netmask (for example, 2000::/64).

For more information about IPv6 deployment in Citrix Virtual Apps and Desktops, see IPv4/IPv6 sup‑
port.

Troubleshooting

Check the basic IPv6 network environment and use ping6 to check whether AD and Delivery Controller
are reachable.

Configure Citrix Customer Experience Improvement Program (CEIP)

February 9, 2021

When you participate in the CEIP, anonymous statistics and usage information are sent to Citrix to help
improve the quality and performance of Citrix products. In addition, a copy of the anonymous data is
sent to Google Analytics (GA) for fast and efficient analysis.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 205

Linux Virtual Delivery Agent 1912 LTSR

Registry settings

By default, you automatically participate in the CEIP when you install the Linux VDA. The first upload
of data occurs approximately seven days after you install the Linux VDA. You can change this default
setting in the registry.

• CEIPSwitch

Registry setting that enables or disables the CEIP (default = 0):

Location: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CEIP

Name: CEIPSwitch

Value: 1 = disabled, 0 = enabled

When unspecified, the CEIP is enabled.

You can run the following command on a client to disable the CEIP:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SOFTWARE\

Citrix\CEIP" -v "CEIPSwitch" -d "1"
2 <!--NeedCopy-->

• GASwitch

Registry setting that enables or disables GA (default = 0):

Location: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CEIP

Name: GASwitch

Value: 1 = disabled, 0 = enabled

When unspecified, GA is enabled.

You can run the following command on a client to disable GA:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SOFTWARE\

Citrix\CEIP" -v "GASwitch" -d "1"
2 <!--NeedCopy-->

• DataPersistPath

Registry setting that controls the data persisting path (default = /var/xdl/ceip):

Location: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CEIP

Name: DataPersistPath

Value: String

You can run the following command to set this path:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 206

Linux Virtual Delivery Agent 1912 LTSR

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SOFTWARE\

Citrix\CEIP" -v "DataPersistPath" -d "your_path"
2 <!--NeedCopy-->

If the configured path does not exist or cannot be accessed, data is saved in the default path.

CEIP data collected from the Linux VDA

The following table gives an example of the types of anonymous information collected. The data does
not contain any details that identify you as a customer.

Data Point Key Name Description

Machine GUID machine_guid Identifying the machine where

the data originates
AD solution ad_solution Text string denoting the
machine’s domain joining
method
Linux kernel version kernel_version Text string denoting the
machine’s kernel version
LVDA version vda_version Text string denoting the
installed version of the Linux
VDA.
LVDA update or fresh install update_or_fresh_install Text string denoting the current
Linux VDA package is being
freshly installed or updated
LVDA installed method install_method Text string denoting that the
current Linux VDA package is
installed by using MCS, PVS,
easy install, or manual
installation.
HDX 3D pro enabled or not hdx_3d_pro Text string denoting whether
HDX 3D Pro is enabled on the
machine
VDI mode enabled or not vdi_mode Text string denoting whether
VDI mode is enabled
System Locale system_locale Text string denoting the locale
of this machine

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 207

Linux Virtual Delivery Agent 1912 LTSR

Data Point Key Name Description

LVDA key services last restart ctxhdx ctxvda The last restart time of the
time ctxhdx and ctxvda services,
in the format of dd‑hh:mm:ss,
for example, 10‑17:22:19
GPU type gpu_type Denoting the GPU type of the
machine
CPU cores cpu_cores Integer denoting the number of
CPU cores of the machine
CPU frequency cpu_frequency Float denoting the CPU
frequency in MHz
Physical memory size memory_size Integer denoting the physical
memory size in KB
Launched session number session_launch Integer denoting the number of
sessions launched (logged on
or reconnected) on the
machine at the time we collect
this data point
Linux OS name and version os_name_version Text string denoting the Linux
OS name and version of the
machine
Session key session_key Identifying the session where
the data originates
Resource type resource_type Text string denoting the
resource type of the launched
session: desktop or
<appname>
Active session time active_session_time Used to save the session’s
active times. One session can
have multiple active times
because the session can
disconnect/reconnect
Session duration time session_duration_time Used to save the session’s
duration from logon to logoff
Receiver client type receiver_type Integer denoting the type of
Citrix Workspace app used to
launch the session

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 208

Linux Virtual Delivery Agent 1912 LTSR

Data Point Key Name Description

Receiver client version receiver_version Text string denoting the version

of Citrix Workspace app used to
launch the session
Printing count printing_count Integer denoting the number of
times the session uses the
printing function
USB redirection count usb_redirecting_count Integer denoting the number of
times the session uses a USB
device
Gfx Provider type gfx_provider_type Text string denoting the
graphics provider type of the
session
Shadowing count shadow_count Integer denoting the number of
times the session has been
shadowed
User selected Language ctxism_select Composed long string that
contains all languages that
users have selected
Smartcard redirecting count scard_redirecting_count Integer denoting the number of
times smart card redirection is
used for session logons and
user authentication for
in‑session apps

Configure USB redirection

July 7, 2021

USB devices are shared between Citrix Workspace app and the Linux VDA desktop. When a USB device
is redirected to the desktop, the user can use the USB device as if it were locally connected.

USB redirection includes three main areas of functionality:

• Open‑source project implementation (VHCI)

• VHCI service
• USB service

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 209

Linux Virtual Delivery Agent 1912 LTSR

Open‑source VHCI:

This portion of the USB redirection feature develops a general USB device sharing system over an IP
network. It consists of a Linux kernel driver and some user mode libraries that allow you to communi‑
cate with the kernel driver to get all the USB data. In the Linux VDA implementation, Citrix reuses the
kernel driver of VHCI. However, all the USB data transfers between the Linux VDA and Citrix Workspace
app are encapsulated in the Citrix ICA protocol package.

VHCI service:

The VHCI service is an open‑source service provided by Citrix to communicate with the VHCI kernel
module. This service works as a gateway between VHCI and the Citrix USB service.

USB service:

The USB service represents a Citrix module that manages all the virtualization and data transfers on
the USB device.

How USB redirection works

Typically, if a USB device is redirected successfully to the Linux VDA, one or more device nodes are
created in the system /dev path. Sometimes, however, the redirected device is not usable for an active
Linux VDA session. USB devices rely on drivers to function properly and some devices require special
drivers. If drivers are not provided, the redirected USB devices are inaccessible to the active Linux VDA
session. To ensure USB device connectivity, install the drivers and configure the system properly.

The Linux VDA supports a list of USB devices that are successfully redirected to and from the client. In
addition, the device is properly mounted, especially the USB disk, allowing the user to access the disk
without any additional configuration.

Supported USB devices

The following devices have been verified to support this version of the Linux VDA. Other devices might
be freely used, with unexpected results:

Note:

The Linux VDA supports only USB 2.0 protocols.

USB mass storage device VID:PID File system

Netac Technology Co., Ltd 0dd8:173c FAT32

Kingston Datatraveler 101 II 0951:1625 FAT32

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 210

Linux Virtual Delivery Agent 1912 LTSR

USB mass storage device VID:PID File system

Kingston Datatraveler GT101 G2 1567:8902 FAT32

SanDisk SDCZ80 flash drive 0781:5580 FAT32
WD HDD 1058:10B8 FAT32

USB 3D mouse VID:PID

3DConnexion SpaceMouse Pro 046d: c62b

USB scanner VID:PID

Epson Perfection V330 photo 04B8: 0142

Configure USB redirection

A Citrix policy controls whether USB device redirection is enabled or disabled. In addition, the type of
device can also be specified using a Delivery Controller policy. When configuring USB redirection for
the Linux VDA, configure the following policy and rules:

• Client USB device redirection policy

• Client USB device redirection rules

Enable USB redirection policy

In Citrix Studio, enable (or disable) USB device redirection to and from the client (for workstation hosts
only).

In the Edit Setting dialog:

1. Select Allowed.
2. Click OK.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 211

Linux Virtual Delivery Agent 1912 LTSR

Set USB redirection rules

After enabling the USB redirection policy, set redirection rules using Citrix Studio by specifying which
devices are allowed (or denied) on the Linux VDA.

In the Client USB device redirection rules dialog:

1. Click New to add a redirection rule, or click Edit to review an existing rule.
2. After creating (or editing) a rule, click OK.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 212

Linux Virtual Delivery Agent 1912 LTSR

For more information about configuring generic USB redirection, see Citrix Generic USB Redirection
Configuration Guide.

Build the VHCI kernel module

USB redirection depends on the VHCI kernel modules (usb-vhci-hcd.ko and usb-vhci-iocif
.ko). These modules are part of the Linux VDA distribution (as part of the RPM package). They are
compiled based on the official Linux distribution kernels and are noted in the following table:

Supported Linux distribution Kernel version

RHEL 7.7, CentOS 7.7 3.10.0‑1062

SUSE 12.3 4.4.73‑5‑default
Ubuntu 18.04 4.15.0‑45‑generic
Ubuntu 16.04 4.4.0‑142‑generic

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 213

Linux Virtual Delivery Agent 1912 LTSR

Important:

If the kernel of your machine is not compatible with the driver built for the Linux VDA, the USB
service might fail to start. In this case, you can use the USB redirection feature only if you build
your own VHCI kernel modules.

Verify whether your kernel is consistent with the modules built by Citrix

On the command line, run the following command to verify whether the kernel is consistent:

1 insmod /opt/Citrix/VDA/lib64/usb-vhci-hcd.ko
2 <!--NeedCopy-->

If the command runs successfully, the kernel module has loaded successfully and the version is con‑
sistent with the one installed by Citrix.

If the command runs with errors, the kernel is inconsistent with the Citrix module and must be re‑
built.

Rebuild the VHCI kernel module

If your kernel module is inconsistent with the Citrix version, do the following:

1. Download the LVDA source code from the Citrix download site. Select the file contained in the
section “Linux Virtual Delivery Agent (sources).”

2. Unzip the citrix‑linux‑vda‑sources.zip file. Navigate to linux‑vda‑souces/vhci‑hcd‑

1.15.tar.bz2 and unzip the VHCI source files by using tar xvf vhci‑hcd‑1.15.tar.bz2.

3. Build the kernel module based on the header files and the Module.symvers file. Use the follow‑
ing steps to install the kernel header files and create Module.symvers based on the appropriate
Linux distribution:

RHEL/CentOS:

1 yum install kernel-devel

2 <!--NeedCopy-->

SUSE 12:

1 zypper install kernel-devel

2
3 zypper install kernel-source
4 <!--NeedCopy-->

Ubuntu:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 214

Linux Virtual Delivery Agent 1912 LTSR

1 apt-get install linux-headers

2 <!--NeedCopy-->

Tip:

If the installation is successful, there is a kernel folder resembling:

/usr/src/kernels/3.10.0‑327.10.1.el7.x86_64

4. In the /usr/src/kernels/3.10.0‑327.10.1.el7.x86_64 folder, verify that the Module.symvers file is

present. If this file is not in the folder, build the kernel (by running the following commands in
sequence: make oldconfig; make prepare; make modules; make) to get this file or
copy it from /usr/src/kernels/3.10.0‑327.10.1.el7.x86_64‑obj/x86_64/defaults/module.*

5. Run the following commands to install the development tools.

RHEL/CentOS:

1 yum groupinstall 'Development Tools'

2 <!--NeedCopy-->

Ubuntu 18.04:

1 apt install build-essential

2 apt install libelf-dev
3 <!--NeedCopy-->

Ubuntu 16.04:

1 apt install build-essential

2 <!--NeedCopy-->

6. In the vhci‑hcd‑1.15/Makefile file, change the Makefile of VCHI and set KDIR to the kernel direc‑
tory:

1 #KDIR = $(BUILD_PREFIX)/lib/modules/$(KVERSION)/build
2
3 KDIR = /usr/src/kernels/3.10.0-327.10.1.el7.x86_64
4 <!--NeedCopy-->

7. In the vhci‑hcd‑1.15/ folder, run make to build the VHCI kernel.

Note:

If the build was successful, usb-vhci-hcd.ko and usb-vhci-iocifc.ko are cre‑

ated in the vhci‑hcd‑1.15/ folder.

8. Replace the kernel module with the newly built one: cp ‑f usb‑vhci‑*.ko /opt/Citrix/VDA/lib64/

9. Restart the USB service:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 215

Linux Virtual Delivery Agent 1912 LTSR

1 service ctxusbsd restart

2 <!--NeedCopy-->

10. Log off and back on to the session again. Check whether USB redirection is functioning.

Troubleshoot kernel building issues

• A kernel building error might occur on specific kernels of Ubuntu 16. The error reads
implicit declaration of function ‘copy\\_to\\_user’, see the following
screen capture.

The error occurs due to header file changes in the kernels. As a workaround, add the #include
<linux/uaccess.h> line to the vhci-hcd-1.15/usb-vhci-iocifc.c file.

• A kernel building error might occur on kernel 4.15.0‑29‑generic of Ubuntu 16. The error
reads ‘ driver\\_attr\\_debug_output’ undeclared, see the following screen cap‑
ture.

The error occurs when symbols are missing on the kernel. As a workaround, disable the macro
definition for DEBUG in the vhci-hcd-1.15/usb-vhci-iocifc.c and vhci-hcd
-1.15/usb-vhci-hcd.c files.

Troubleshoot USB redirection issues

Use the information in this section to troubleshoot various issues that you might encounter when
using the Linux VDA.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 216

Linux Virtual Delivery Agent 1912 LTSR

Unable to unmount the redirected USB disk**

For the access control of all USB disks redirected from Citrix Workspace app, the Linux VDA manages all
these devices under administrative privilege to ensure that only the owner can access the redirected
device. As a result, the user cannot unmount the device without the administrative privilege.

File lost when you stop redirecting a USB disk

If you redirect a USB disk to a session and try to modify it (for example, create some files on the disk),
then stop redirecting it immediately using the toolbar of Citrix Workspace app, the file you modified or
created can be lost. This issue occurs because when you write data to a file system, the system mounts
the memory cache in the file system. The data is not written to the disk itself. If you stop redirecting
using the toolbar of Citrix Workspace app, there is no time remaining for the data being flushed to the
disk, which results in lost data. To resolve this issue, use the sync command in a terminal to flush data
to the disk before stopping USB redirection.

No devices in the toolbar of Citrix Workspace app

Sometimes, you might not be able to see devices listed in the toolbar of Citrix Workspace app, which
indicates that no USB redirection is taking place. If you encounter the issue, verify the following:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 217

Linux Virtual Delivery Agent 1912 LTSR

• The policy is configured to allow USB redirection

• The Kernel module is compatible with your kernel

Note:

The Devices tab is not available in Citrix Workspace app for Linux.

Failed redirection when USB devices can be seen in the toolbar of Citrix Workspace app, but
are labeled policy restricted

When the issue occurs, do the following:

• Configure the Linux VDA policy to enable redirection.

• Check whether any additional policy restrictions are configured in the registry of Citrix Work‑
space app. Check DeviceRules in the registry path to ensure that the device is not denied access
by this setting:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\GenericUSB

For more information, see Knowledge Center

article How to Configure Automatic Redirection of USB Devices.

A USB device is redirected successfully, but I cannot use it in my session

Usually, only supported USB devices can be redirected. Other devices might be redirected to an active
Linux VDA session too. In this case, for every redirected device, a node owned by the user is created
in the system /dev path. However, it is the drivers and the configuration that determine whether the
user can use the device successfully. If you find a device owned (plugged in) but inaccessible, add the
device to an unrestricted policy.

Note:

In the case of USB drives, the Linux VDA configures and mounts the disk. The user (and only the
owner who installed it) can access the disk without any additional configuration. This might not
be the case for devices that are not in the supported device list.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 218

Linux Virtual Delivery Agent 1912 LTSR

Configure session reliability

June 9, 2020

Citrix introduces the session reliability feature to all supported Linux platforms. Session reliability is
enabled by default.

Session reliability reconnects ICA sessions seamlessly across network interruptions. For more infor‑
mation about session reliability, see Auto client reconnect and session reliability.

Note: Data transmitted through a session reliability connection is in plain text by default. For security
purposes, We recommend that you enable TLS encryption. For more information about TLS encryp‑
tion, see Secure user sessions using TLS.

Configuration

Policy settings in Citrix Studio

You can set the following policies for session reliability in Citrix Studio:

• Session reliability connections

• Session reliability timeout
• Session reliability port number
• Reconnection UI transparency level

For more information, see Session reliability policy settings and Auto client reconnect policy
settings.

Note: After setting the Session reliability connections or Session reliability port number policy,
restart the VDA service and the HDX service, in this order, for your settings to take effect.

Settings on the Linux VDA

• Enable/disable the session reliability TCP listener

By default, the session reliability TCP listener is enabled and listening on port 2598. To disable the
listener, run the following command.

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\WinStations\cgp" -v "
fEnableWinStation" -d "0x00000000"
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 219

Linux Virtual Delivery Agent 1912 LTSR

Note: Restart the HDX service for your settings to take effect. Disabling the TCP listener does not
disable session reliability. Session reliability is still available through other listeners (for example, SSL)
if the feature is enabled through the Session reliability connections policy.

• Session reliability port number

You can also set the session reliability port number by using the following command (using port num‑
ber 2599 as an example).

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\WinStations\cgp" -v "PortNumber"
-d "2599"
2 <!--NeedCopy-->

Note: Restart the HDX service for your setting to take effect. If the port number has been set through
the policy setting in Citrix Studio, your setting on the Linux VDA is ignored. Ensure that the firewall on
the VDA is configured not to prohibit network traffic through the set port.

• Server‑to‑client keep‑alive interval

Session reliability keep‑alive messages are sent between the Linux VDA and the ICA client when there
is no activity in the session (for example, no mouse movement, no screen update). The keep‑alive
messages are used to detect whether the client is still responsive. If there is no response from the
client, the session is suspended until the client reconnects. This setting specifies the number of sec‑
onds between successive keep‑alive messages. By default, this setting is not configured. To configure
it, run the following command (using 10 seconds as an example).

1 /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SOFTWARE\

Citrix\XTEConfig" -t "REG_DWORD" -v "CgpServerToClientKeepAlive"
-d "10" --force

• Client‑to‑server keep‑alive interval

This setting specifies the number of seconds between successive keep‑alive messages sent from the
ICA client to the Linux VDA. By default, this setting is not configured. To configure it, run the following
command (using 10 seconds as an example).

1 /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SOFTWARE\

Citrix\XTEConfig" -t "REG_DWORD" -v "CgpClientToServerKeepAlive"
-d "10" --force
2 <!--NeedCopy-->

Troubleshooting

Unable to launch sessions after enabling session reliability through the policy setting.

To work around this issue, do the following:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 220

Linux Virtual Delivery Agent 1912 LTSR

1. Ensure that the VDA service and HDX service are restarted, in this order, after you enable session
reliability through the policy setting in Citrix Studio.

2. On the VDA, run the following command to verify that the session reliability TCP listener is run‑
ning (using port 2598 as an example).

1 netstat -an | grep 2598

2 <!--NeedCopy-->

If there is no TCP listener on the session reliability port, enable the listener by running the fol‑
lowing command.

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\SYSTEM\

CurrentControlSet\Control\Citrix\WinStations\cgp" -v "
fEnableWinStation" -d "0x00000001"
2 <!--NeedCopy-->

Soft keyboard

June 18, 2020

The soft keyboard feature is available in a Linux virtual desktop or application session. The soft key‑
board shows or hides automatically when you enter or leave an input field.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 221

Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 222

Linux Virtual Delivery Agent 1912 LTSR

Note:

The feature is available for RHEL 7.7, CentOS 7.6, SUSE 12.3, Ubuntu 16.04, and Ubuntu 18.04. It
is supported on Citrix Workspace app for iOS and for Android.

Enable and disable the feature

The feature is disabled by default. Use the ctxreg utility to enable or disable the feature. The feature
configuration on a given Linux VDA applies to all sessions on that VDA.

To enable the feature:

1. Run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\

CurrentControlSet\Control\Citrix\VirtualChannels\MrVc" -v "
Enabled" -d "0x00000001"
2 <!--NeedCopy-->

2. In Citrix Studio, set the Automatic keyboard display policy to Allowed.

3. (Optional) For RHEL 7 and CentOS 7, run the following command to configure Intelligent Input
Bus (IBus) as the default IM service:

1 echo "GTK_IM_MODULE=ibus" >>/etc/bashrc

2 <!--NeedCopy-->

To disable the feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\CurrentControlSet\

Control\Citrix\VirtualChannels\MrVc" -v "Enabled" -d "0x00000000"
2 <!--NeedCopy-->

Note:

The preceding settings take effect when you log on to a new session or log off and back on to the
current session.

Limitations

• The feature might not work as expected with Google Chrome, LibreOffice, and other apps.

• To display the soft keyboard again after manually hiding it, click a non‑input field and then the
current input field again.

• The soft keyboard might not appear when you click from one input field to another in a web
browser. To work around this issue, click a non‑input field and then the target input field.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 223

Linux Virtual Delivery Agent 1912 LTSR

• The feature does not support Unicode characters and double‑byte characters (such as Chinese,
Japanese, and Korean characters).

• The soft keyboard is not available for password input fields.

• The soft keyboard might overlap the current input field. In this case, move the app window or
scroll up your screen to move the input field to an accessible position.

• Due to compatibility issues between Citrix Workspace app and Huawei tablets, the soft key‑
board appears on Huawei tablets even with a physical keyboard connected.

Client Input Method Editor (IME)

May 20, 2020

Overview

Double‑byte characters such as Chinese, Japanese, and Korean characters must be typed through an
IME. Type such characters with any IME that is compatible with Citrix Workspace app on the client side,
such as the Windows native CJK IME.

Installation

This feature is installed automatically when you install the Linux VDA.

Usage

Open a Citrix Virtual Apps or Citrix Virtual Desktops session as per usual.

Change your input method as required on the client side to start using the client IME feature.

Known issues

• Double‑clicking a cell in a Google spreadsheet is a must before you can use the client IME feature
to type characters in the cell.
• The client IME feature is not automatically disabled in Password fields.
• The IME user interface does not follow the cursor in the input area.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 224

Linux Virtual Delivery Agent 1912 LTSR

Support for multiple language inputs

June 18, 2020

As of the Linux VDA Version 1.4, Citrix has added support for published applications. Users can access
a desired Linux application without the Linux desktop environment.

However, the native language bar on the Linux VDA was unavailable to the published application be‑
cause the language bar is highly integrated with the Linux desktop environment. As a result, users
were unable to input text in a language that requires IME such as Chinese, Japanese, or Korean. Fur‑
ther, it was also not possible for users to switch between keyboard layouts during an application ses‑
sion.

To address those issues, this feature provides a language bar for published applications that accept
text input. The language bar enables users to select a server‑side IME and to switch between keyboard
layouts during an application session.

Configuration

You can use the ctxreg utility to enable or disable this feature (disabled by default). The feature con‑
figuration on a given Linux VDA server applies to all applications published on that VDA.

The configuration key is “HKEY_LOCAL_MACHINE \SYSTEM\CurrentControlSet\Control\Citrix\LanguageBar”

and the type is DWORD.

To enable this feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE \SYSTEM\

CurrentControlSet\Control\Citrix\LanguageBar" -v "Enabled" -d "0
x00000001"
2 <!--NeedCopy-->

To disable this feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE \SYSTEM\

CurrentControlSet\Control\Citrix\LanguageBar" -v "Enabled" -d "0
x00000000"
2 <!--NeedCopy-->

Usage

The usage is straightforward.

1. Enable the feature.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 225

Linux Virtual Delivery Agent 1912 LTSR

2. Access a published application that can accept text input. A language bar appears in the session,
alongside the application.

3. From the drop‑down menu, select Region & Language to add the desired language (input
source).

4. Select the IME or keyboard layout from the drop‑down menu.

5. Type a language using the selected IME or keyboard layout.

Note:

• When you change a keyboard layout on the VDA‑side language bar, ensure that the
same keyboard layout is used on the client side (running Citrix Workspace app).
• The accountsservice package must be upgraded to Version 0.6.37 or later before you
can perform settings in the Region & Language dialog box.

Dynamic keyboard layout synchronization

September 9, 2020

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 226

Linux Virtual Delivery Agent 1912 LTSR

Previously, the keyboard layouts on the Linux VDA and on the client device had to be the same. For
example, when the keyboard layout changed from English to French on the client device but not on
the VDA, key mapping issues might occur and persist until the VDA changed to French too.

Citrix addresses the issue by automatically synchronizing the keyboard layout of the VDA with the
keyboard layout of the client device. Anytime the keyboard layout on the client device changes, the
layout on the VDA follows suit.

Tip�

This feature is supported on Citrix Workspace app for Windows and is compatible with both pub‑
lished apps and desktops.

Configuration

This feature is disabled by default. Use the ctxreg utility to enable or disable this feature. The feature
configuration on a given Linux VDA applies to all sessions on that VDA.

The configure key is “HKEY_LOCAL_MACHINE\SYSTEM \CurrentControlSet\Control\Citrix\SyncKeyboardLayout”

and the type is DWORD.

To enable this feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\LanguageBar" -v "SyncKeyboardLayout
" -d "0x00000001"
2 <!--NeedCopy-->

To disable this feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\LanguageBar" -v "SyncKeyboardLayout
" -d "0x00000000"
2 <!--NeedCopy-->

Usage

With this feature enabled, when the keyboard layout changes on the client device during a session,
the keyboard layout of the session changes accordingly.

For example, if you change the keyboard layout on a client device to French (FR):

Then the keyboard layout of the Linux VDA session also changes to “fr.”

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 227

Linux Virtual Delivery Agent 1912 LTSR

In an application session, you can see this automatic change if you have enabled the language bar:

In a desktop session, you can see this automatic change in the task bar:

Client IME user interface synchronization

June 18, 2020

Overview

To date, the client IME user interface (including the composition window and candidate window) was
positioned in the upper left corner of the screen. It did not follow the cursor and sometimes was
located far from the cursor in the text input area:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 228

Linux Virtual Delivery Agent 1912 LTSR

Citrix enhances usability and further improves the seamless experience with the client IME as fol‑
lows:

Note:

The feature is available for RHEL 7.x, CentOS 7.x, Ubuntu 16.04, Ubuntu 18.04, and SUSE 12.x. It
is supported on Citrix Workspace app for Windows and for Mac.

To use the feature in RHEL 7.x desktop sessions, you must enable IBus. For example, set the user
interface language to one that requires an IME to input, or add GTK_IM_MODULE=ibus to the
${HOME}/.config/imsettings/xinputrc file.

The feature installs automatically, but you must enable the feature before you can use it.

Enable and disable the feature

The feature is disabled by default. Use the ctxreg utility to enable or disable the feature. The feature
configuration on a given Linux VDA applies to all sessions on that VDA.

To enable the feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\LanguageBar" -v "SyncClientIME" -d
"0x00000001"
2 <!--NeedCopy-->

To disable the feature, run the command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKEY_LOCAL_MACHINE\System\

CurrentControlSet\Control\Citrix\LanguageBar" -v "SyncClientIME" -d
"0x00000000"
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 229

Linux Virtual Delivery Agent 1912 LTSR

HDX Insight

August 20, 2022

Overview

HDX Insight is part of the Citrix Application Delivery Management (ADM) and is based on the popular
industry standard AppFlow. It enables IT to deliver an exceptional user experience by providing un‑
precedented end‑to‑end visibility into the Citrix ICA traffic that passes through the Citrix ADC or Citrix
SD‑WAN application networking fabric.

The Linux VDA partially supports the HDX Insight feature. Because the End User Experience Manage‑
ment (EUEM) feature is not implemented, some data points related to time duration are not avail‑
able.

Installation

No dependent packages need installation.

Usage

HDX Insight analyzes the ICA messages passed through the Citrix ADC between Citrix Workspace app
and the Linux VDA.

You must set up a NetScaler Insight Center deployment with the Linux VDA and enable the HDX Insight
feature. You can migrate your NetScaler Insight Center deployment to Citrix ADM without losing the
existing configuration, settings, or data. For more information, see Migrate from NetScaler Insight
Center to Citrix ADM.

Troubleshooting

No data points are displayed

There might be two causes:

• HDX Insight is not configured correctly.

For example, AppFlow is not enabled on the Citrix ADC or an incorrect Citrix ADC instance is
configured on the Citrix ADM.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 230

Linux Virtual Delivery Agent 1912 LTSR

• The ICA Control Virtual Channel is not started on the Linux VDA.

ps aux | grep -i ctxctl

If ctxctl is not running, contact your administrator to report a bug to Citrix.

No application data points are displayed

Verify that the seamless virtual channel is enabled and a seamless application is launched for a
while.

Adaptive transport

November 15, 2020

Previously available as an experimental feature, adaptive transport is a fully supported feature in this
release.

Adaptive transport is a data transport mechanism for Citrix Virtual Apps and Desktops. It is faster,
more scalable, improves application interactivity, and is more interactive on challenging long‑haul
WAN and internet connections. For more information, see Adaptive transport.

Enable adaptive transport

In Citrix Studio, verify that the HDX Adaptive Transport policy is set to Preferred or Diagnostic mode.
Preferred is selected by default.

• Preferred: Adaptive transport over Enlightened Data Transport (EDT) is used when possible,
with fallback to TCP.
• Diagnostic mode: EDT is forced on and fallback to TCP is disabled.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 231

Linux Virtual Delivery Agent 1912 LTSR

Disable adaptive transport

To disable adaptive transport, set the HDX Adaptive Transport policy to Off in Citrix Studio.

Troubleshooting

Check whether adaptive transport is enabled

To check whether UDP listeners are running, run the following command.

1 netstat -an | grep "1494\|2598"

2 <!--NeedCopy-->

In normal circumstances, the output is similar to the following.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 232

Linux Virtual Delivery Agent 1912 LTSR

1 udp 0 0 0.0.0.0:2598 0.0.0.0:*

2
3 udp 0 0 :::1494 :::*
4 <!--NeedCopy-->

Tracing On

August 9, 2021

Overview

Collecting logs and reproducing issues slow down the diagnostics and degrade the user experience.
The Tracing On feature eases such efforts. Tracing is enabled for the Linux VDA by default.

Configuration

The ctxlogd daemon and the setlog utility are now included in the Linux VDA release package. By
default, the ctxlogd daemon starts after you install and configure the Linux VDA.

ctxlogd daemon

All the other services that are traced depend on the ctxlogd daemon. You can stop the ctxlogd
daemon if you do not want to keep the Linux VDA traced.

setlog utility

Tracing On is configured using the setlog utility, which is under the /opt/Citrix/VDA/bin/ path. Only
the root user has the privilege to run it. You can use the GUI or run commands to view and change the
configurations. Run the following command for help with the setlog utility:

1 setlog help
2 <!--NeedCopy-->

Values By default, Log Output Path is set to /var/log/xdl/hdx.log, Max Log Size is set to 200 MB,
and you can save up to two old log files under Log Output Path.

View the current setlog values:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 233

Linux Virtual Delivery Agent 1912 LTSR

1 setlog values
2
3 log_path (Log Output Path) = /var/log/xdl/hdx.log
4
5 log_size (Max Log Size (MiB)) = 200
6
7 log_count (Max Old Log Files) = 2
8 <!--NeedCopy-->

View or set a single setlog value:

1 setlog value <name> [<value>]

2 <!--NeedCopy-->

For example:

1 setlog value log_size 100

2 <!--NeedCopy-->

Levels By default, log levels are set to warning (case‑insensitive).

To view log levels set for different components, run the following command:

1 setlog levels
2 <!--NeedCopy-->

To set log levels (including Disabled, Inherited, Verbose, Information, Warnings, Errors, and Fatal Er‑
rors), run the following command:

1 setlog level <class> [<level>]

2 <!--NeedCopy-->

Log Level Command Parameter (Case‑Insensitive)

Disabled none
Inherited inherit
Verbose verbose
Information info
Warnings warning
Errors error
Fatal Errors fatal

The <class> variable specifies one component of the Linux VDA. To cover all components, set it to
all. For example:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 234

Linux Virtual Delivery Agent 1912 LTSR

1 setlog level all error

2 <!--NeedCopy-->

Flags By default, the flags are set as follows:

1 setlog flags
2
3 DATE = true
4
5 TIME = true
6
7 NAME = true
8
9 PID = true
10
11 TID = false
12
13 SID = true
14
15 UID = false
16
17 GID = false
18
19 CLASS = false
20
21 LEVEL = false
22
23 FUNC = true
24
25 FILE = false
26 <!--NeedCopy-->

View the current flags:

1 setlog flags
2 <!--NeedCopy-->

View or set a single log flag:

1 setlog flag <flag> [<state>]

2 <!--NeedCopy-->

Restore Defaults Revert all levels, flags, and values to the default settings:

1 setlog default
2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 235

Linux Virtual Delivery Agent 1912 LTSR

Important:

The ctxlogd service is configured using the /var/xdl/.ctxlog file, which only root users can cre‑
ate. Other users do not have write permission to this file. Citrix recommends that root users not
give write permission to other users. Failure to comply can cause the arbitrary or malicious con‑
figuration to ctxlogd, which can affect server performance and therefore the user experience.

Troubleshooting

The ctxlogd daemon fails and you cannot restart the ctxlogd service when the /var/xdl/.ctxlog
file is missing (for example, accidentally deleted).

/var/log/messages:

1 Apr 1 02:28:21 RH72 citrix-ctxlogd[17881]: Failed to open logging

configuration file.
2
3 Apr 1 02:28:21 RH72 systemd: ctxlogd.service: main process exited, code
=exited, status=1/FAILURE
4
5 Apr 1 02:28:21 RH72 systemd: Unit ctxlogd.service entered failed state.
6
7 Apr 1 02:28:21 RH72 systemd: ctxlogd.service failed.
8 <!--NeedCopy-->

To solve this issue, run setlog as a root user to recreate the /var/xdl/.ctxlog file. Then restart the
ctxlogd service on which other services depend.

Shadow sessions

June 18, 2020

The session shadowing feature allows domain administrators to view users’ICA sessions in an intranet.
The feature uses noVNC to connect to the ICA sessions and is supported only with RHEL 7.x and Ubuntu
16.04.
Note:

To use the session shadowing feature, the version of Citrix Director must be 7.16 or later.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 236

Linux Virtual Delivery Agent 1912 LTSR

Installation and configuration

Dependencies

Two new dependencies, python-websockify and x11vnc, are required for session shadowing.
The python-websockify and x11vnc dependencies are automatically installed when you install
the Linux VDA on Ubuntu 16.04. On RHEL 7.x, you must manually install python-websockify and
x11vnc after you install the Linux VDA.

Run the following command on RHEL 7.x to install python-websockify and x11vnc (x11vnc
version 0.9.13 or later).

1 sudo yum install -y python-websockify x11vnc

2 <!--NeedCopy-->

To resolve python-websockify and x11vnc, enable the following repositories on RHEL 7.x:

• Extra Packages for Enterprise Linux (EPEL)

The EPEL repository is required for both python-websockify and x11vnc. Run the follow‑
ing command to enable the EPEL repository:

1 sudo yum install https://dl.fedoraproject.org/pub/epel/epel-

release-latest-$(rpm -E '%{
2 rhel }
3 ').noarch.rpm
4 <!--NeedCopy-->

• Optional RPMs

Run either of the following commands to enable the optional RPMs repository for installing
some dependency packages of x11vnc:

For workstation:

1 subscription-manager repos --enable=rhel-7-workstation-optional-

rpms
2 <!--NeedCopy-->

For server:

1 subscription-manager repos --enable=rhel-7-server-optional-rpms

2 <!--NeedCopy-->

Port

The session shadowing feature automatically selects available ports from within 6001‑6099 to build
up connections from the Linux VDA to Citrix Director. Therefore, the number of ICA sessions that you

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 237

Linux Virtual Delivery Agent 1912 LTSR

can shadow concurrently is limited to 99. Ensure that enough ports are available to meet your require‑
ments, especially for multi‑session shadowing.

Registry

The following table lists related registries:

Registry Description Default Value

EnableSessionShadowing Enables or disables the session 1 (Enabled)

shadowing feature
ShadowingUseSSL Determines whether to encrypt 0 (Disabled)
the connection between the
Linux VDA and Citrix Director

Run the ctxreg command on the Linux VDA to change the registry values. For example, to disable
session shadowing, run the following command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\

VirtualDesktopAgent" -v "EnableSessionShadowing" -d 0x00000000

SSL

The noVNC connection between the Linux VDA and Citrix Director uses the WebSocket protocol. For
session shadowing, whether ws:// or wss:// is chosen is determined by the previously mentioned
“ShadowingUseSSL”registry. By default, ws:// is chosen. However, for security reasons, Citrix rec‑
ommends that you use wss:// and install certificates on each Citrix Director client and on each Linux
VDA server. Citrix disclaims any security responsibility for the Linux VDA session shadowing by using
ws://.

Obtain server and root SSL certificates Certificates must be signed by a trusted Certificate Author‑
ity (CA).

A separate server certificate (including the key) is required for each Linux VDA server on which you
want to configure SSL. A server certificate identifies a specific computer, so you must know the Fully
Qualified Domain Name (FQDN) of each server. For convenience, you can use a wildcard certificate
for the whole domain instead. In this case, you must know at least the domain name.

In addition to installing a server certificate on each server, you must install a root certificate from the
same CA on each Citrix Director client that communicates with the Linux VDA server. Root certificates
are available from the same CAs that issue the server certificates. You can install server and client

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 238

Linux Virtual Delivery Agent 1912 LTSR

certificates from a CA that is bundled with your operating system, from an enterprise CA (a CA that your
organization makes accessible to you), or from a CA not bundled with your operating system. Consult
the security team of your organization to find out which of the methods they require for obtaining
certificates.

Important:

• The Common Name for a server certificate must be the exact FQDN of the Linux VDA server or
at least the correct wildcard plus domain characters. For example, vda1.basedomain.com or
*.basedomain.com.
• Hashing algorithms including the SHA1 and MD5 are too weak for signatures in digital certifi‑
cates for some browsers to support. So SHA‑256 is specified as the minimum standard.

Install a root certificate on each Citrix Director client Session shadowing uses the same registry‑
based certificate store as IIS, so you can install root certificates using IIS or the Microsoft Management
Console (MMC) Certificates snap‑in. When you receive a certificate from a CA, you can restart the Web
Server Certificate Wizard in IIS and the wizard installs the certificate. Alternatively, you can view and
import certificates on the computer using the MMC and add the certificate as a standalone snap‑in.
Internet Explorer and Google Chrome import the certificates installed on your operation system by
default. For Mozilla Firefox, you must import your root SSL certificates on the Authorities tab of Cer‑
tificate Manager.

Install a server certificate and its key on each Linux VDA server Name the server certificates
“shadowingcert.*”and the key file “shadowingkey.*”(* can indicate the format, for example, shadow‑
ingcert.csr and shadowingkey.key). Put server certificates and key files under the path /etc/xdl/shad‑
owingssl and protect them properly with restricted permissions. An incorrect name or path makes
the Linux VDA unable to find a specific certificate or key file and therefore causes connection failure
with Citrix Director.

Usage

From Citrix Director, find the target session and click Shadow in the Session Details view to send a
shadowing request to the Linux VDA.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 239

Linux Virtual Delivery Agent 1912 LTSR

After the connection initializes, a confirmation appears on the ICA session client (not the Citrix Director
client) to ask the user for permission to shadow the session.

If the user clicks Yes, a window appears on the Citrix Director side, indicating that the ICA session is
being shadowed.

For more information about the usage, see the Citrix Director Documentation.

Limitations

• Session shadowing is designed for use in an Intranet only. It does not work for external networks
even connecting through Citrix Gateway. Citrix disclaims any responsibility for the Linux VDA
session shadowing in an external network.
• With session shadowing enabled, a domain administrator can only view the ICA sessions, but
has no permission to write or control it.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 240

Linux Virtual Delivery Agent 1912 LTSR

• After an administrator clicks Shadow from Citrix Director, a confirmation appears to ask the user
for permission to shadow the session. A session can be shadowed only when the session user
gives the permission.
• The previously mentioned confirmation has a timeout limitation, which is 20s. A shadowing
request fails when the time runs out.
• One ICA session can be shadowed by only one administrator in one Citrix Director window. If
an ICA session has been shadowed by administrator A and meanwhile, administrator B sends
a shadowing request, the confirmation for getting the user permission reappears on the user
device. If the user agrees, the shadowing connection for administrator A stops and a new shad‑
owing connection is built for administrator B. It is the same if another shadowing request for
the same ICA session is sent by the same administrator.
• To use session shadowing, install Citrix Director 7.16 or later.
• A Citrix Director client uses an FQDN rather than an IP address to connect to the target Linux
VDA server. Therefore, the Citrix Director client must be able to resolve the FQDN of the Linux
VDA server.

Troubleshooting

If session shadowing fails, perform debugging on both the Citrix Director client and the Linux VDA.

On the Citrix Director client

Through the developer tools of the browser, check the output logs on the Console tab. Or, check the
response of the ShadowLinuxSession API on the Network tab. If the confirmation for getting the user
permission appears but the connection fails to be built, manually ping the FQDN of the Linux VDA to
verify that Citrix Director can resolve the FQDN. If there is an issue with the wss:// connection, check
your certificates.

On the Linux VDA

Verify that the confirmation for getting the user permission appears in response to a shadowing re‑
quest. If it does not, check the vda.log and hdx.log files for clues. To obtain the vda.log file, do the
following:

1. Find the /etc/xdl/ctx‑vda.conf file. Uncomment the following line to enable the vda.log config‑
uration:

Log4jConfig=”/etc/xdl/log4j.xml”

2. Open /etc/xdl/log4j.xml, locate the com.citrix.dmc part, and change “info”to “trace”as follows:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 241

Linux Virtual Delivery Agent 1912 LTSR

1 <!-- Broker Agent Plugin - Director VDA plugin Logger -->

2
3 <logger name="com.citrix.dmc">
4
5 <level value="trace"/>
6
7 </logger>
8 <!--NeedCopy-->

3. Run the service ctxvda restart command to restart the ctxvda service.

If there is an error during connection build‑up:

1. Check for any firewall limitation that stops session shadowing from opening the port.
2. Verify that certificates and key files are named properly and put under the correct path if it is
the SSL scenario.
3. Verify that there are enough ports left between 6001‑6099 for new shadowing requests.

Support Citrix Workspace app for HTML5

June 18, 2020

Starting with this release, you can use Citrix Workspace app for HTML5 to access Linux virtual apps
and desktops directly without connecting your client to Citrix Gateway. For information about Citrix
Workspace app for HTML5, see the Citrix documentation.

Enable this feature

This feature is disabled by default. To enable it, do the following:

1. In Citrix StoreFront, enable Citrix Workspace app for HTML5.

For the detailed procedure, see Step 1 of Knowledge Center article CTX208163.

2. Enable WebSocket connections.

a) In Citrix Studio, set the WebSockets connections policy to Allowed.

You can also set the other WebSocket policies. For a full list of the WebSocket policies, see
WebSockets policy settings.

b) On the VDA, restart the ctxvda service and the ctxhdx service, in this order, for your
setting to take effect.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 242

Linux Virtual Delivery Agent 1912 LTSR

c) On the VDA, run the following command to check whether the WebSocket listener is run‑
ning.

netstat -an | grep 8008

When the WebSocket listener is running, the command output is similar to the following:

tcp 0 0 :::8008 :::* LISTEN

Note: You can also enable TLS encryption to secure WebSocket connections. For information
about enabling TLS encryption, see Secure user sessions using TLS.

Monitor Linux sessions in Citrix Director

June 1, 2023

The following metrics are available for Linux sessions in Citrix Director. To view the metrics, find the
target session in Citrix Director and check the Session Details panel.

• ICA RTT

Starting with Linux VDA Version 1903, ICA RTT metrics are available. To view ICA RTT metrics,
use Citrix Director 1903 or later and create the ICA round trip calculation and ICA round trip
calculation interval policies in Citrix Studio. For information about policy creation, see Create
a policy using Studio.

• Protocol

Starting with Linux VDA Version 1909, protocol information is available. The transport protocol
of a Linux session appears as UDP or TCP in the Session Details panel.

Monitor service daemon

June 18, 2020

The monitor service daemon monitors key services by performing periodical scans. When detecting
exceptions, the daemon restarts or stops service processes and cleans up process residuals for releas‑
ing resources. The detected exceptions are recorded in the /var/log/xdl/ms.log file.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 243

Linux Virtual Delivery Agent 1912 LTSR

Configuration

The monitor service daemon starts automatically when you start the VDA.

You can configure the feature through the scanningpolicy.conf, rulesets.conf, and whitelist.conf
files with administrator privileges. The configuration files are located at /opt/Citrix/VDA/sbin.

To make your changes in the scanningpolicy.conf, rulesets.conf, and whitelist.conf files take effect,
run the following command to restart the monitor service daemon.

1 service ctxmonitorservice restart

2 <!--NeedCopy-->

• scanningpolicy.conf

This configuration file enables or disables the monitor service daemon. It sets the service detec‑
tion interval and specifies whether to repair detected exceptions.

– MonitorEnable: true/false (true by default)

– DetectTime: 20 (unit: seconds, default value: 20, minimum value: 5)

– AutoRepair: true/false (true by default)

– MultBalance: false

– ReportAlarm: false

• rulesets.conf

This configuration file specifies the target services to monitor. There are four monitored services
by default as shown in the following screen capture.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 244

Linux Virtual Delivery Agent 1912 LTSR

To configure each service to monitor, set the following fields.

– MonitorUser: all

– MonitorType: 3

– ProcessName: <> (The process name cannot be left blank and must be exactly matched.)

– Operation: 1/2/4/8 (1 = stop the service when exceptions are detected. 2 = kill the service
when exceptions are detected. 4 = restart the service. 8 = clean up the Xorg process resid‑
uals.)

– DBRecord: false

• whitelist.conf

The target services specified in the rulesets.conf file must also be configured in whitelist.conf
file. The white list configuration is a secondary filter for security.

To configure the white list, include only the process names (which must be match exactly) in the
whitelist.conf file. For an example, see the following screen capture.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 245

Linux Virtual Delivery Agent 1912 LTSR

Note:

Before you stop the ctxvda, ctxhdx, and ctxpolicyd services, run the service
ctxmonitorservice stop command to stop the monitor service daemon. Otherwise, the
monitor service daemon restarts the services you stopped.

Secure user sessions using TLS

February 18, 2022

As of Version 7.16, the Linux VDA supports TLS encryption for secure user sessions. TLS encryption is
disabled by default.

Enable TLS encryption

To enable TLS encryption for secure user sessions, obtain certificates and enable TLS encryption on
both the Linux VDA and the Delivery Controller (the Controller).

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 246

Linux Virtual Delivery Agent 1912 LTSR

Obtain certificates

Obtain server certificates in PEM format and root certificates in CRT format from a trusted Certificate
Authority (CA). A server certificate contains the following sections:

• Certificate
• Unencrypted private key
• Intermediate certificates (optional)

An example of a server certificate:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 247

Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 248

Linux Virtual Delivery Agent 1912 LTSR

Enable TLS encryption

Enable TLS encryption on the Linux VDA On the Linux VDA, use the enable_vdassl.sh tool to en‑
able (or disable) TLS encryption. The tool is located in the /opt/Citrix/VDA/sbin directory. For infor‑
mation about the options available in the tool, run the /opt/Citrix/VDA/sbin/enable_vdassl.sh ‑help
command.

Tip: A server certificate must be installed on each Linux VDA server and root certificates must be in‑
stalled on each Linux VDA server and client.

Enable TLS encryption on the Controller

Note:

You can enable TLS encryption only for entire delivery groups. You cannot enable TLS encryption
for specific applications.

In a PowerShell window on the Controller, run the following commands in sequence to enable TLS
encryption for the target delivery group.

1. Add-PSSnapin citrix.*
2. Get-BrokerAccessPolicyRule –DesktopGroupName 'GROUPNAME'| Set-
BrokerAccessPolicyRule –HdxSslEnabled $true

Note:

To ensure that only VDA FQDNs are contained in an ICA session file, you can also run the Set‑
BrokerSite –DnsResolutionEnabled $true command. The command enables DNS resolution.
If you disable DNS resolution, an ICA session file discloses VDA IP addresses and provides FQDNs
only for the TLS‑related items such as SSLProxyHost and UDPDTLSPort.

To disable TLS encryption on the Controller, run the following commands in sequence:

1. Add-PSSnapin citrix.*
2. Get-BrokerAccessPolicyRule –DesktopGroupName 'GROUPNAME'| Set-
BrokerAccessPolicyRule –HdxSslEnabled $false
3. Set-BrokerSite –DnsResolutionEnabled $false

Troubleshooting

The following “Can’t assign requested address”error might occur in Citrix Workspace app for Windows
when you try to access a published desktop session:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 249

Linux Virtual Delivery Agent 1912 LTSR

As a workaround, add an entry to the hosts file, which is similar to:

<IP address of the Linux VDA> <FQDN of the Linux VDA>

On Windows machines, the hosts file typically locates at C:\Windows\System32\drivers\etc

\hosts.

Secure user sessions using DTLS

June 18, 2020

DTLS encryption is a fully supported feature starting with the 7.18 release. By default, this feature is
enabled on the Linux VDA. For more information, see Transport Layer Security.

Enable DTLS encryption

Verify that adaptive transport is enabled

In Citrix Studio, verify that the HDX Adaptive Transport policy is set to Preferred or Diagnostic
mode.

Enable SSL encryption on the Linux VDA

On the Linux VDA, use the enable_vdassl.sh tool to enable (or disable) SSL encryption. The tool is
located at /opt/Citrix/VDA/sbin. For information about the options available in the tool, run the /op‑
t/Citrix/VDA/sbin/enable_vdassl.sh –h command.
Note:

Currently, the Linux VDA supports both DTLS 1.0 and DTLS 1.2. DTLS 1.2 requires Citrix Receiver

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 250

Linux Virtual Delivery Agent 1912 LTSR

for Windows 4.12, or Citrix Workspace app 1808 for Windows or later. If your client supports
only DTLS 1.0 (for example, Citrix Receiver for Windows 4.11), set SSLMinVersion to TLS_1.0
and SSLCipherSuite to COM or ALL using the enable_vdassl.sh tool.

Support for smart cards

August 10, 2021

You can use a smart card connected to the client device for authentication when logging on to a Linux
virtual desktop session. This feature is implemented through smart card redirection over the ICA
smart card virtual channel. You can also use the smart card within the session. Use cases include
adding a digital signature to a document, encrypting or decrypting an email, or authenticating to a
website that requires smart card authentication.
The Linux VDA uses the same configuration as the Windows VDA for this feature. For more information,
see the Configure the smart card environment section in this article.
The availability of pass‑through authentication by using smart cards is contingent on the following
conditions:

• The Linux VDA is installed on RHEL 7.7.

• Smart cards supported by CoolKey are used.
• Citrix Workspace app for Windows is used.

Note:

Using a mapped smart card within a Linux VDA session to sign on to Citrix Gateway is not officially
supported.

Install the Linux VDA software on RHEL 7.7

Install the Linux VDA software using the RPM package manager or easy install, see the Installation
overview section.
After the VDA installation is complete, verify that the VDA can register to the Delivery Controller and
the published Linux desktop sessions can be launched successfully using password authentication.

Ensure that CoolKey supports your smart card

CoolKey is a widely used smart card driver on RHEL. CoolKey supports four types of smart cards, which
are CoolKey cards, CAC, PIV, and PKCS#15. But the number of cards that are formally supported and
validated is still limited (see Smart Card Support in Red Hat Enterprise Linux).

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 251

Linux Virtual Delivery Agent 1912 LTSR

In this article, the YubiKey 4 smart card is used as an example to illustrate the configuration. YubiKey 4
is an all‑in‑one USB CCID PIV device that can easily be purchased from Amazon or other retail vendors.
The CoolKey driver supports YubiKey 4.

If your organization requires some other more advanced smart card, prepare a physical machine with
RHEL 7.7 and the CoolKey package installed. For information about the CoolKey installation, see
Install the smart card driver. Insert your smart card, and run the following command to verify that
CoolKey supports your smart card:

1 pkcs11-tool --module libcoolkeypk11.so --list-slots

2 <!--NeedCopy-->

If CoolKey supports your smart card, the command output is similar to the following where slot infor‑
mation is contained.

Configuration

Prepare a root certificate

A root certificate is used to verify the certificate on the smart card. Do the following to download and
install a root certificate.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 252

Linux Virtual Delivery Agent 1912 LTSR

1. Obtain a root certificate in PEM format, typically from your CA server.

You can run a command similar to the following to convert a DER file (*.crt, *.cer, *.der) to PEM.
In the following command example, certnew.cer is a DER file.

1 openssl x509 -inform der -in certnew.cer -out certnew.pem

2 <!--NeedCopy-->

2. Install the root certificate to the openssl directory. The certnew.pem file is used as an exam‑
ple.

1 cp certnew.pem <path where you install the root certificate>

2 <!--NeedCopy-->

To create a path for installing the root certificate, run sudo mdkir -p <path where you
install the root certificate>.

Configure the NSS database

The Linux VDA logon module relies on the NSS database to access smart cards and certificates. Do the
following to configure the NSS database.

1. Add the previously mentioned root certificate to the NSS database.

1 certutil -A -n "My Corp Root" -t "CT,C,C" -a -d /etc/pki/nssdb -i

/etc/pki/CA/certs/certnew.pem
2 <!--NeedCopy-->

2. Run the following command to verify that the root certificate is added to the NSS database suc‑
cessfully.

1 certutil -L -d /etc/pki/nssdb
2 <!--NeedCopy-->

The command output is similar to the following if the root certificate is added successfully.

3. Check whether CoolKey is installed in the NSS PKCS#11 library.

1 modutil -list -dbdir /etc/pki/nssdb

2 <!--NeedCopy-->

The command output is similar to the following if the CoolKey module is installed.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 253

Linux Virtual Delivery Agent 1912 LTSR

If the CoolKey module is not installed, run the following command to install the module manu‑
ally, and then check the installation again.

1 modutil -add "CoolKey PKCS #11 Module" -libfile libcoolkeypk11.so

-dbdir /etc/pki/nssdb
2 <!--NeedCopy-->

4. Configure the pam_pkcs11 module.

The pam_pkcs11 module relies on the local VDA configuration to verify user certificates. The
default root certificate used by pam_pkcs11 is located at /etc/pam_pkcs11/cacerts/. Each root
certificate in this path has a hash link. Run the following commands to install the prepared root
certificate and to configure pam_pkcs11.

1 yum install pam_pkcs11

2
3 mkdir /etc/pam_pkcs11/cacerts/
4
5 cp certnew.pem /etc/pam_pkcs11/cacerts/
6
7 cacertdir_rehash /etc/pam_pkcs11/cacerts
8 <!--NeedCopy-->

Configure the smart card environment

You can use the ctxsmartlogon.sh script to configure the smart card environment or do the configura‑
tion manually.

• Use the ctxsmartlogon.sh script to configure the smart card environment

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 254

Linux Virtual Delivery Agent 1912 LTSR

Note:

The ctxsmartlogon.sh script adds PKINIT information to the default realm. You can change
this setting through the /etc/krb5.conf configuration file.

Before using smart cards for the first time, run the ctxsmartlogon.sh script to configure the
smart card environment.
Tip:

If you have used SSSD for domain joining, restart the SSSD service after you run ctxsmartl‑
ogon.sh.

1 sudo /opt/Citrix/VDA/sbin/ctxsmartlogon.sh
2 <!--NeedCopy-->

The results resemble the following:

You can also disable smart cards by running the ctxsmartlogon.sh script:

1 sudo /opt/Citrix/VDA/sbin/ctxsmartlogon.sh
2 <!--NeedCopy-->

The results resemble the following:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 255

Linux Virtual Delivery Agent 1912 LTSR

• Manually configure the smart card environment

The Linux VDA uses the same smart card environment with the Windows VDA. In the environ‑
ment, multiple components must be configured, including the Domain Controller, Microsoft
Certificate Authority (CA), Internet Information Services, Citrix StoreFront, and Citrix Workspace
app. For information about the configuration based on the YubiKey 4 smart card, see Knowl‑
edge Center article CTX206156.

Before proceeding to the next step, ensure that all components are correctly configured, the
private key and user certificate are downloaded to the smart card, and you can successfully log
on to the Windows VDA using the smart card.

Install the PC/SC Lite packages

PCSC Lite is an implementation of the Personal Computer/Smart Card (PC/SC) specification in Linux.
It provides a Windows smart card interface for communicating to smart cards and readers. Smart card
redirection in the Linux VDA is implemented on the PC/SC level.

Run the following command to install the PC/SC Lite packages.

1 yum install pcsc-lite pcsc-lite-ccid pcsc-lite-libs

2 <!--NeedCopy-->

Install the smart card driver

CoolKey is a widely used smart card driver on RHEL. If CoolKey is not installed, run the following com‑
mand to install it.

1 yum install coolkey

2 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 256

Linux Virtual Delivery Agent 1912 LTSR

Install the PAM modules for smart card authentication

Run the following command to install the pam_krb5 and krb5‑pkinit modules.

1 yum install pam_krb5 krb5-pkinit

2 <!--NeedCopy-->

The pam_krb5 module is a pluggable authentication module that PAM‑aware applications can use to
check passwords and obtain ticket‑granting tickets from the Key Distribution Center (KDC). The krb5‑
pkinit module contains the PKINIT plug‑in that allows clients to obtain initial credentials from the KDC
using a private key and a certificate.

Configure the pam_krb5 module

The pam_krb5 module interacts with the KDC to get Kerberos tickets using certificates in the smart
card. To enable pam_krb5 authentication in PAM, run the following command:

1 authconfig --enablekrb5 --update

2 <!--NeedCopy-->

In the /etc/krb5.conf configuration file, add PKINIT information according to the actual realm.

Note:

The pkinit_cert_match option specifies matching rules that the client certificate must match
before it is used to attempt PKINIT authentication. The syntax of the matching rules is:

[relation-operator] component-rule …

where relation-operator can be either &&, meaning all component rules must match, or
||, meaning only one component rule must match.

Here is an example of a generic krb5.conf file:

1 EXAMPLE.COM = {
2
3
4 kdc = KDC. EXAMPLE.COM
5
6 auth_to_local = RULE:[1:$1@$0]
7
8 pkinit_anchors = FILE:<path where you install the root certificate
>/certnew.pem
9
10 pkinit_kdc_hostname = KDC.EXAMPLE.COM
11
12 pkinit_cert_match = ||<EKU>msScLogin,<KU>digitalSignature
13
14 pkinit_eku_checking = kpServerAuth

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 257

Linux Virtual Delivery Agent 1912 LTSR

15
16 }
17
18 <!--NeedCopy-->

The configuration file resembles the following after you add the PKINIT information.

Configure PAM authentication

PAM configuration files tell what modules are used for PAM authentication. To add pam_krb5 as an
authentication module, add the following line to the /etc/pam.d/smartcard‑auth file:

auth [success=done ignore=ignore default=die] pam_krb5.so preauth_options

=X509_user_identity=PKCS11:/usr/lib64/pkcs11/libcoolkeypk11.so

The configuration file resembles the following after modification if SSSD is used.

The configuration file resembles the following after modification if Winbind is used.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 258

Linux Virtual Delivery Agent 1912 LTSR

The configuration file resembles the following after modification if Centrify is used.

(Optional) Single sign‑on by using smart cards

Single sign‑on (SSO) is a Citrix feature that implements pass‑through authentication with virtual desk‑
top and application launches. This feature reduces the number of times that users type their PIN. To
use SSO with the Linux VDA, configure Citrix Workspace app. The configuration is the same with the
Windows VDA. For more information, see Knowledge Center article CTX133982.

Enable the smart card authentication as follows when configuring the group policy in Citrix Workspace
app.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 259

Linux Virtual Delivery Agent 1912 LTSR

Fast smart card logon

Fast smart card is an improvement over the existing HDX PC/SC‑based smart card redirection. It im‑
proves performance when smart cards are used in high‑latency WAN environments. For more infor‑
mation, see Smart cards.

The Linux VDA supports fast smart card on the following versions of Citrix Workspace app:

• Citrix Receiver for Windows 4.12

• Citrix Workspace app 1808 for Windows and later

Enable fast smart card logon on the client Fast smart card logon is enabled by default on the
VDA and disabled by default on the client. On the client, to enable fast smart card logon, include the
following parameter in the default.ica file of the associated StoreFront site:

1 [WFClient]
2 SmartCardCryptographicRedirection=On
3 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 260

Linux Virtual Delivery Agent 1912 LTSR

Disable fast smart card logon on the client To disable fast smart card logon on the client, remove
the SmartCardCryptographicRedirection parameter from the default.ica file of the associated Store‑
Front site.

Usage

Log on to the Linux VDA by using a smart card

You can use a smart card to log on to the Linux VDA in both SSO and non‑SSO scenarios.

• In the SSO scenario, you are automatically logged on to StoreFront by using the cached smart
card certificate and PIN. When you launch a Linux virtual desktop session in StoreFront, the PIN
is passed to the Linux VDA for smart card authentication.

• In the non‑SSO scenario, you are prompted to select a certificate and type a PIN to log on to
StoreFront.

When you launch a Linux virtual desktop session in StoreFront, a dialog box for logon to the Linux VDA
appears as follows. The user name is extracted from the certificate in the smart card and you must
type the PIN again for logon authentication.

This behavior is the same with the Windows VDA.

Reconnect to a session by using a smart card

To reconnect to a session, ensure that the smart card is connected to the client device. Otherwise, a
gray caching window appears on the Linux VDA side and exits quickly because reauthentication fails
without the smart card connected. No other prompt is provided in this case to remind you to connect
the smart card.

On the StoreFront side, however, if a smart card is not connected when you try to reconnect to a ses‑
sion, the StoreFront web might give an alert as follows.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 261

Linux Virtual Delivery Agent 1912 LTSR

Limitation

Smart card removal policy

Now, the Linux VDA uses only the default behavior for smart card removal. When you remove the
smart card after logging on to the Linux VDA successfully, the session still keeps connected and the
session screen is not locked.

Support for other smartcards and the PKCS#11 library

Although only the CoolKey smart card is listed on our support list, you can try using other smart
cards and the PKCS#11 library because Citrix is providing a generic smart card redirection solution.
To switch to your specific smart card or the PKCS#11 library:

1. Replace all the libcoolkeypk11.so instances with your PKCS#11 library.

2. To set the path of your PKCS#11 library to the registry, run the following command:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\

CurrentControlSet\Control\Citrix\VirtualChannels\Scard" -v "
PKCS11LibPath" -d "PATH"
2 <!--NeedCopy-->

where PATH points to your PKCS#11 library such as /usr/lib64/pkcs11/libcoolkeypk11.so

3. Disable fast smart card logon on the client.

Double‑hop single sign‑on authentication

June 18, 2020

The feature injects user credentials entered for accessing a StoreFront store to the AuthManager mod‑
ule of Citrix Workspace app for Linux and Citrix Receiver for Linux 13.10. After injection, you can use the

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 262

Linux Virtual Delivery Agent 1912 LTSR

client to access virtual desktops and applications from within a Linux virtual desktop session, without
entering user credentials for a second time.

Note:

This feature is supported on Citrix Workspace app for Linux and Citrix Receiver for Linux 13.10.

To enable the feature:

1. On the Linux VDA, install Citrix Workspace app for Linux or Citrix Receiver for Linux 13.10.

Download the app from the Citrix download page for Citrix Workspace app or for Citrix Receiver.

The default installation path is /opt/Citrix/ICAClient/. If you install the app to a different path,
set the ICAROOT environment variable to point to the actual installation path.

2. In the Citrix StoreFront management console, add the HTTP Basic authentication method for
the target store.

3. Add the following key to the AuthManager configuration file ($ICAROOT/config/AuthManCon‑

fig.xml) for allowing the HTTP Basic authentication:

1 <Protocols>
2 <HTTPBasic>
3 <Enabled>True</Enabled>

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 263

Linux Virtual Delivery Agent 1912 LTSR

4 </HTTPBasic>
5 </Protocols>
6 <!--NeedCopy-->

4. Run the following commands to install the root certificate in the specified directory.

1 cp rootcert.pem $ICAROOT/keystore/cacerts/
2 $ICAROOT/util/ctx_rehash $ICAROOT/keystore/cacerts/
3 <!--NeedCopy-->

5. Run the following command to enable the feature:

1 /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\

CurrentControlSet\Control\Citrix" -v "LurSsonEnabled" -d "0
x00000001"
2 <!--NeedCopy-->

6. Launch a Linux virtual desktop session and start Citrix Workspace app for Linux or Citrix Receiver
for Linux 13.10 within that session.

You are prompted for a store account the first time you start Citrix Workspace app for Linux or
Citrix Receiver for Linux 13.10 within a Linux virtual desktop session. Later on, you are automat‑
ically logged on to the store you specified earlier.

Note:

Enter an HTTPS URL as your store account.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 264

Linux Virtual Delivery Agent 1912 LTSR

Configure unauthenticated sessions

June 18, 2020

Use the information in this article to configure unauthenticated sessions. No special settings are re‑
quired when installing the Linux VDA to use this feature.

Note:

When configuring unauthenticated sessions, consider that session prelaunch is not supported.
Session prelaunch is also not supported on Citrix Workspace app for Android.

Create an unauthenticated store

To support an unauthenticated session on the Linux VDA, create an unauthenticated store using Store‑
Front.

Enable unauthenticated users in a Delivery Group

After creating an unauthenticated store, enable unauthenticated users in a Delivery Group to support
an unauthenticated session. To enable unauthenticated users in a Delivery Group, follow the instruc‑
tions in the Citrix Virtual Apps and Desktops documentation.

Set the unauthenticated session idle time

An unauthenticated session has a default idle timeout of 10 minutes. This value is configured through
the registry setting AnonymousUserIdleTime. Use the ctxreg tool to change this value. For example,
to set this registry setting to five minutes:

1 sudo /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\

CurrentControlSet\Control\Citrix" -v AnonymousUserIdleTime -d 0
x00000005
2 <!--NeedCopy-->

Set the maximum number of unauthenticated users

To set the maximum number of unauthenticated users, use the registry key MaxAnonymousUser‑
Number. This setting limits the number of unauthenticated sessions running on a single Linux VDA
concurrently. Use the ctxreg tool to configure this registry setting. For example, to set the value to
32:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 265

Linux Virtual Delivery Agent 1912 LTSR

1 sudo /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\System\

CurrentControlSet\Control\Citrix" -v MaxAnonymousUserNumber -d 0
x00000020
2 <!--NeedCopy-->

Important:

Limit the number of unauthenticated sessions. Too many sessions being launched concurrently
can cause problems on the VDA, including running out of available memory.

Troubleshooting

Consider the following when configuring unauthenticated sessions:

• Failed to log on to an unauthenticated session.

Verify that the registry was updated to include the following (set to 0):

1 sudo /opt/Citrix/VDA/bin/ctxreg read – k "HKLM\System\CurrentControlSet

\Control\Citrix" – v MaxAnonymousUserNumber
2 <!--NeedCopy-->

Verify that the ncsd service is running and configured to enable passwd cache:

1 ps uax | grep nscd

2 cat /etc/nscd.conf | grep 'passwd' | grep 'enable-cache'
3 <!--NeedCopy-->

Set the passwd cache variable to no if it is enabled, then restart the ncsd service. You might need to
reinstall the Linux VDA after changing this configuration.

• The lock screen button is displayed in an unauthenticated session with KDE.

The lock screen button and menu are disabled by default in an unauthenticated session. However,
they can still be displayed in KDE. In KDE, to disable the lock screen button and menu for a particu‑
lar user, add the following lines to the configuration file $Home/.kde/share/config/kdeglobals. For
example:

1 [KDE Action Restrictions]

2 action/lock_screen=false
3 <!--NeedCopy-->

However, if the KDE Action Restrictions parameter is configured as immutable in a global wide
kdeglobals file such as /usr/share/kde‑settings/kde‑profile/default/share/config/kdeglobals,
the user configuration has no effect.

To resolve this issue, try to modify the system‑wide kdeglobals file to remove the [$i] tag at the
[KDE Action Restrictions] section or directly use the system‑wide configuration to disable the lock

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 266

Linux Virtual Delivery Agent 1912 LTSR

screen button and menu. For details about the KDE configuration, see the KDE System Administra‑
tion/Kiosk/Keys page.

Configure LDAPS

October 7, 2021
Secure LDAP (LDAPS) allows you to enable the Secure Lightweight Directory Access Protocol for your
Active Directory managed domains to provide communication over SSL (Secure Socket Layer)/TLS
(Transport Layer Security).
By default, LDAP communications between client and server applications are not encrypted. LDAP
using SSL/TLS (LDAPS) enables you to protect the LDAP query content between Linux VDA and LDAP
servers.
The following Linux VDA components have dependencies on LDAPS:

• Broker agent: Linux VDA registration to Delivery Controller

• Policy service: Policy evaluation

Configuring LDAPS involves:

• Enable LDAPS on the Active Directory (AD)/LDAP server

• Export the root CA for client use
• Enable/disable LDAPS on Linux VDA
• Configure LDAPS for third‑party platforms
• Configure SSSD
• Configure Winbind
• Configure Centrify
• Configure Quest

Enable LDAPS on the AD/LDAP server

You can enable LDAP over SSL (LDAPS) by installing a properly formatted certificate from either a Mi‑
crosoft certification authority (CA) or a non‑Microsoft CA.

Tip:

LDAP over SSL/TLS (LDAPS) is automatically enabled when you install an Enterprise Root CA on
a domain controller.

For more information about how to install the certificate and verify the LDAPS connection, see How
to enable LDAP over SSL with a third‑party certification authority on the Microsoft Support site.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 267

Linux Virtual Delivery Agent 1912 LTSR

When you have a multi‑tier (such as a two‑tier or three‑tier) certificate authority hierarchy, you do not
automatically have the appropriate certificate for LDAPS authentication on the domain controller.

For information about how to enable LDAPS for domain controllers using a multi‑tier certificate au‑
thority hierarchy, see the LDAP over SSL (LDAPS) Certificate article on the Microsoft TechNet site.

Enable root certificate authority for client use

The client must be using a certificate from a CA that the LDAP server trusts. To enable LDAPS authen‑
tication for the client, import the root CA certificate to a trusted keystore.

For more information about how to export Root CA, see How to export Root Certification Authority
Certificate on the Microsoft Support website.

Enable or disable LDAPS on the Linux VDA

To enable or disable LDAPS for Linux VDA, run the following script (while logged on as an administra‑
tor):

The syntax for this command includes the following:

• Enable LDAP over SSL/TLS with the root CA certificate provided:

1 /opt/Citrix/VDA/sbin/enable_ldaps.sh -Enable pathToRootCA

2 <!--NeedCopy-->

• Fall back to LDAP without SSL/TLS

1 /opt/Citrix/VDA/sbin/enable_ldaps.sh -Disable
2 <!--NeedCopy-->

The Java keystore dedicated for LDAPS is located in /etc/xdl/.keystore. Affected registry keys in‑
clude:

1 HKLM\Software\Citrix\VirtualDesktopAgent\ListOfLDAPServers
2
3 HKLM\Software\Citrix\VirtualDesktopAgent\ListOfLDAPServersForPolicy
4
5 HKLM\Software\Citrix\VirtualDesktopAgent\UseLDAPS
6
7 HKLM\Software\Policies\Citrix\VirtualDesktopAgent\Keystore
8 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 268

Linux Virtual Delivery Agent 1912 LTSR

Configure LDAPS for third‑party platform

Besides the Linux VDA components, several third‑party software components that adhere to the VDA
might also require secure LDAP, such as SSSD, Winbind, Centrify, and Quest. The following sections
describe how to configure secure LDAP with LDAPS, STARTTLS, or SASL sign and seal.

Tip:

Not all of these software components prefer to use SSL port 636 to ensure secure LDAP. And most
of the time, LDAPS (LDAP over SSL on port 636) cannot coexist with STARTTLS on 389.

SSSD

Configure the SSSD secure LDAP traffic on port 636 or 389 as per the options. For more information,
see the SSSD LDAP Linux man page.

Winbind

The Winbind LDAP query uses the ADS method. Winbind supports only the StartTLS method on port
389. Affected configuration files are /etc/samba/smb.conf and /etc/openldap/ldap.conf (for RHEL)
or /etc/ldap/ldap.conf (for Ubuntu). Change the files as follows:

• smb.conf

ldap ssl = start tls

ldap ssl ads = yes
client ldap sasl wrapping = plain

• ldap.conf

TLS_REQCERT never

Alternately, secure LDAP can be configured by SASL GSSAPI sign and seal, but it cannot coexist with
TLS/SSL. To use SASL encryption, change the smb.conf configuration:

ldap ssl = off

ldap ssl ads = no
client ldap sasl wrapping = seal

Centrify

Centrify does not support LDAPS on port 636. However, it does provide secure encryption on port 389.
For more information, see the Centrify site.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 269

Linux Virtual Delivery Agent 1912 LTSR

Quest

Quest Authentication Service does not support LDAPS on port 636, but it provides secure encryption
on port 389 using a different method.

Troubleshooting

The following issues might arise when you use this feature:

• LDAPS service availability

Verify that the LDAPS connection is available on the AD/LDAP server. The port is on 636 by de‑
fault.
• Linux VDA registration failed when LDAPS is enabled
Verify that the LDAP server and ports are configured correctly. Check the Root CA Certificate first
and ensure that it matches the AD/LDAP server.
• Incorrect registry change by accident
If the LDAPS related keys were updated by accident without using enable_ldaps.sh, it might
break the dependency of LDAPS components.
• LDAP traffic is not encrypted through SSL/TLS from Wireshark or any other network mon‑
itoring tools
By default, LDAPS is disabled. Run /opt/Citrix/VDA/sbin/enable_ldaps.sh to force it.
• There is no LDAPS traffic from Wireshark or any other networking monitoring tool
LDAP/LDAPS traffic occurs when Linux VDA registration and Group Policy evaluation occur.
• Failed to verify LDAPS availability by running ldp connect on the AD server
Use the AD FQDN instead of the IP Address.
• Failed to import Root CA certificate by running the /opt/Citrix/VDA/sbin/enable_ldaps.sh
script
Provide the full path of the CA certificate, and verify that the Root CA Certificate is the correct
type. Generally speaking, it is supposed to be compatible with most of the Java Keytool types
supported. If it is not listed in the support list, you can convert the type first. Citrix recommends
the base64 encoded PEM format if you encounter a certificate format problem.
• Failed to show the Root CA certificate with Keytool ‑list
When you enable LDAPS by running /opt/Citrix/VDA/sbin/enable_ldaps.sh, the certificate is
imported to /etc/xdl/.keystore, and the password is set to protect the keystore. If you forget the
password, you can rerun the script to create a keystore.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 270

Linux Virtual Delivery Agent 1912 LTSR

Configure Xauthority

October 9, 2020

The Linux VDA supports environments that use X11 display functionality (including xterm and gvim
) for interactive remoting. This feature provides a security mechanism necessary to ensure secure
communication between XClient and XServer.

There are two methods to secure permission for this secure communication:

• Xhost. By default, Xhost allows only the localhost XClient to communicate with XServer. If you
choose to allow a remote XClient to access XServer, the Xhost command must be run to grant
permission on the specific machine. Or, you can alternately use xhost + to allow any XClient to
connect to XServer.
• Xauthority. The .Xauthority file can be found in each user’s home directory. It is used
to store credentials in cookies used by xauth for authentication of XServer. When an XServer
instance (Xorg) is started, the cookie is used to authenticate connections to that specific display.

How it works

When Xorg starts up, a .Xauthority file is passed to the Xorg. This .Xauthority file contains the
following elements:

• Display number
• Remote request protocol
• Cookie number

You can browse this file using the xauth command. For example:

1 # xauth -f ~/.Xauthority
2
3 # > list
4
5 # > us01msip06:107 MIT-MAGIC-COOKIE-1
fb228d1b695729242616c5908f11624b
6 <!--NeedCopy-->

If XClient connects to the Xorg remotely, two prerequisites must be met:

• Set the DISPLAY environment variable to the remote XServer.

• Get the .Xauthority file which contains one of the cookie numbers in Xorg.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 271

Linux Virtual Delivery Agent 1912 LTSR

Configure Xauthority

To enable Xauthority on the Linux VDA for remote X11 display, you must create the following two reg‑
istry keys:

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\System\

CurrentControlSet\Control\Citrix\Xorg" -t "REG_DWORD" -v "
XauthEnabled" -d "0x00000001" --force
2
3 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\System\
CurrentControlSet\Control\Citrix\Xorg" -t "REG_DWORD" -v "ListenTCP"
-d "0x00000001" --force
4 <!--NeedCopy-->

After enabling Xauthority, pass the .Xauthority file to XClient manually or by mounting a shared
home directory:

• Pass the .Xauthority file to XClient manually

After launching an ICA session, the Linux VDA generates the .Xauthority file for the XClient
and stores the file in the logon user’s home directory. You can copy this .Xauthority file to
the remote XClient machine, and set the DISPLAY and XAUTHORITY environment variables. DIS‑
PLAY is the display number stored in the .Xauthority file and XAUTHORITY is the file path of
Xauthority. For an example, see the following command:

1 export DISPLAY={
2 Display number stored in the Xauthority file }
3
4
5 export XAUTHORITY={
6 the file path of .Xauthority }
7
8 <!--NeedCopy-->

Note:

If the XAUTHORITY environment variable is not set, the ~/.Xauthority file is used by
default.

• Pass the .Xauthority file to XClient by mounting a shared home directory

The convenient way is to mount a shared home directory for the logon user. When the Linux
VDA starts an ICA session, the .Xauthority file is created under the logon user’s home di‑
rectory. If this home directory is shared with XClient, the user does not need to transmit this
.Xauthority file to XClient manually. After the DISPLAY and XAUTHORITY environment vari‑
ables are set correctly, the GUI is displayed in XServer desktop automatically.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 272

Linux Virtual Delivery Agent 1912 LTSR

Troubleshooting

If Xauthority does not work, follow the troubleshooting steps:

1. As an administrator with root privilege, retrieve all Xorg cookies:

1 ps aux | grep -i xorg

2 <!--NeedCopy-->

This command displays the Xorg process and the parameters passed to Xorg while starting. An‑
other parameter displays which .Xauthority file is used. For example:

1 /var/xdl/xauth/.Xauthority110
2 <!--NeedCopy-->

Display the cookies using the Xauth command:

1 Xauth -f /var/xdl/xauth/.Xauthority110
2 <!--NeedCopy-->

2. Use the Xauth command to show the cookies contained in ~/.Xauthority. For the same
display number, the displayed cookies must be the same in the .Xauthority files of Xorg
and XClient.

3. If the cookies are the same, check the remote display port accessibility by using the IP address
of the Linux VDA (for example, 10.158.11.11) and the published desktop display number (for
example, 160).

Run the following command on the XClient machine:

1 telnet 10.158.11.11 6160

2 <!--NeedCopy-->

The port number is the sum of 6000 + <display number>.

If this telnet operation fails, the firewall might be blocking the request.

Federated Authentication Service

June 2, 2023

Overview

The Citrix Federated Authentication Service (FAS) is a privileged component designed to integrate with
Active Directory Certificate Services. It dynamically issues certificates for users, allowing them to log

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 273

Linux Virtual Delivery Agent 1912 LTSR

on to an Active Directory environment as if they had a smart card. This functionality allows StoreFront
to use a broader range of authentication options, such as Security Assertion Markup Language (SAML)
assertions. SAML is commonly used as an alternative to traditional Windows user accounts on the
Internet.
Note:

To use SAML authentication, configure FAS on the VDA properly.

Starting with CU3, the Linux VDA uses short connections to transmit data with FAS servers.

The following diagram shows FAS integrated with a Microsoft Certification Authority and providing
support services for StoreFront and VDAs.

Trusted StoreFront servers contact the FAS when users request access to the Citrix environment. The
FAS grants a ticket that allows a single Citrix Virtual Apps or Citrix Virtual Desktops session to authenti‑
cate 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

FAS is supported on Windows Server 2008 R2 and later.

• We recommend installing FAS on a server that does not contain other Citrix components.
• The Windows Server must be secured for accessing a registration authority certificate and a
private key to automatically issue certificates for domain users and for accessing those user cer‑
tificates and private keys.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 274

Linux Virtual Delivery Agent 1912 LTSR

In a Citrix Virtual Apps or Citrix Virtual Desktops Site:

• The Delivery Controllers must be minimum version 7.9.

• The StoreFront server must be minimum version 3.6 (version provided with the XenApp and
XenDesktop 7.9 ISO).
• The Linux VDAs must be minimum version 7.18. Verify that the Federated Authentication Service
Group Policy configuration has been applied correctly to the VDAs before creating the Machine
Catalog in the usual way. For more information, see the Configure Group Policy section in this
article.

References:

• Active Directory Certificate Services

https://social.technet.microsoft.com/wiki/contents/articles/1137.active‑directory‑certificate‑
services‑ad‑cs‑introduction.aspx
• Configuring Windows for Certificate Logon
http://support.citrix.com/article/CTX206156
• Installing the Federated Authentication Service
Federated Authentication Service

Configure Windows for Certificate Logon

For information on configuring Windows for certificate logon, open Knowledge Center article
CTX206156 to download and read the Smart_card_config_Citrix_Env.pdf file (hereinafter “the
PDF file”). Perform the following steps according to the PDF file while noting the differences or
complements that are given in each step. Pay special attention to the target machine you are
operating on, for example, the AD, Delivery Controller, or StoreFront.

Set up a Windows domain (on AD)

Install domain controller roles See the Installing Domain Controller Roles section of the PDF
file.

During installation of the Active Directory Certificate Services, ensure that the following options are
selected:

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 275

Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 276

Linux Virtual Delivery Agent 1912 LTSR

Open http://localhost/certsrv/ to check whether it displays the following welcome page.

If yes, the Active Directory Certificate Services are installed successfully.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 277

Linux Virtual Delivery Agent 1912 LTSR

Prepare the Certificate Authority for smart card usage No complement. See the Preparing the
Certificate Authority for Smart card usage section of the PDF file.

Issue a Domain Controller certificate No complement. See the Issuing a Domain Controller Cer‑
tificate section of the PDF file.

Configure Microsoft IIS for HTTPS (on StoreFront)

Configure HTTPS on Microsoft IIS No complement. See the Configuring HTTPS on Microsoft IIS
section of the PDF file.

Non‑domain joined computers

See the Non‑Domain Joined Computers section of the PDF file.

Retrieve the CA Certificate from the Microsoft CA (on AD) No complement. See the Retrieving
the CA Certificate from the Microsoft CA section of the PDF file.

Install the trusted CA certificate on Windows No complement. See the Installing the Trusted CA
Certificate on Windows section of the PDF file.

Configure Citrix StoreFront (on StoreFront)

Create the store See the Creating the Store section of the PDF file.

After the preceding IIS configuration, the base URL of the common store is forcibly set to https:
// rather than http://. Because FAS does not share the store with smart cards, a new store is
needed for FAS. The Linux VDA FAS is compatible with any StoreFront authentication methods. For
example, the FAS store can be configured to use passwords or SAML, but cannot use both at the same
time. When SAML is selected, the URL of StoreFront automatically redirects to IdP and the password
authentication method is ignored.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 278

Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 279

Linux Virtual Delivery Agent 1912 LTSR

Start Internet Explorer and open the URL of the FAS store (for example, https://mzgwy-ddc.xd
.local/Citrix/FASWeb).

Note: The URL of the FAS store must have Web appended.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 280

Linux Virtual Delivery Agent 1912 LTSR

Install and set up FAS

The installation and setup process consists of the following steps:

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 Ser‑
vice to use your certificate authority
5. Configure user rules

For instructions on each of the steps, see Federated Authentication Service. Note the following differ‑
ences or complements in each of the steps. Pay special attention to the target machine you operating
on, for example, the AD, Delivery Controller, StoreFront, or the FAS server.

Install the Federated Authentication Service (on the FAS server)

For security, install FAS on a dedicated server that is secured in a similar way to a domain controller
or certificate authority.

Enable the Federated Authentication Service plug‑in on a StoreFront store (on StoreFront)

Ensure that the following command uses the same FAS store name that you typed when configuring
StoreFront. For example, FAS is the store name in this example:

$StoreVirtualPath = “/Citrix/FAS”

Configure the Delivery Controller (on Delivery Controller)

To use the Federated Authentication Service, configure the Delivery Controller to trust the StoreFront
servers that can connect to it: run the Set‑BrokerSite ‑TrustRequestsSentToTheXmlServicePort
$true PowerShell cmdlet. Sometimes, you might need to run Add-PSSnapin citrix.* first.

Configure Group Policy (on the FAS server and on the AD)

You must be an administrator to be able to perform Steps 1–7 in this section. Step 1 must be done on
the FAS server and Steps 2–7 must be done on the AD.

After you complete Steps 1–7, check in the Registry Editor of the FAS server to confirm that the FAS
policy has been set.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 281

Linux Virtual Delivery Agent 1912 LTSR

Enable in‑session certificate support The Linux VDA does not support in‑session certificates.

Use the Federated Authentication Service administration console (on the FAS server)

No complement. See the Federated Authentication Service article.

Deploy certificate templates (on the FAS server)

No complement. See the Federated Authentication Service article.

Set up Active Directory Certificate Services (on the FAS server)

No complement. See the Federated Authentication Service article.

Authorize the Federated Authentication Service (on the FAS server)

No complement. See the Federated Authentication Service article.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 282

Linux Virtual Delivery Agent 1912 LTSR

Configure user rules (on the FAS server)

No complement. See the Federated Authentication Service article.

For more information, see also the Delegated Enrollment Agents and Access Control List configura‑
tion parts in the Security considerations section of the Federated Authentication Service article.

Federated Authentication Service ADFS deployment

For information on how to deploy the ADFS IdP for Federated Authentication Service, see Federated
Authentication Service ADFS deployment.

Configure the Linux VDA

Set FAS servers

For fresh Linux VDA installation, to use FAS, type the FQDN of each FAS server when you are asked for
CTX_XDL_FAS_LIST during the execution of ctxinstall.sh or ctxsetup.sh. Because the Linux VDA does
not support AD Group Policy, you can provide a semicolon‑separated list of FAS servers instead. If any
server address is removed, fill its blank with the <none> text string and keep the sequence of server
addresses without any changes.

For upgrading an existing Linux VDA installation, you can rerun ctxsetup.sh to set the FAS servers. Or
you can run the following commands to set the FAS servers and to restart the ctxvda service to make
your setting take effect.

1 sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\

VirtualDesktopAgent\Authentication\UserCredentialService" -t "REG_SZ
" -v "Addresses" -d "<Your-FAS-Server-List>" --force
2
3 service ctxvda restart
4 <!--NeedCopy-->

To update the FAS servers through ctxreg, run the following commands:

1 sudo /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\

VirtualDesktopAgent\Authentication\UserCredentialService" -v "
Addresses" -d "<Your-FAS-Server-List>"
2
3 service ctxvda restart
4 <!--NeedCopy-->

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 283

Linux Virtual Delivery Agent 1912 LTSR

Install a root CA certificate

For the verification of users’certificates, install the root CA certificate on the VDA. Obtain the AD root
certificate from the preceding Retrieve the CA Certificate from the Microsoft CA (on AD) step, or
download its DER format from the root CA server http://CA-SERVER/certsrv.

Note:

The following commands also apply to configuring an intermediate certificate.

Convert a DER file (.crt, .cer, .der) to PEM by running the command similar to the following:

1 sudo openssl x509 -inform der -in root.cer -out root.pem

2 <!--NeedCopy-->

Then, install the root CA certificate to the openssl directory by running the command similar to the
following:

1 sudo cp root.pem /etc/pki/CA/certs/

2 <!--NeedCopy-->

Note:

Do not put the root CA certificate under the /root path. Otherwise, FAS does not have the read
permission to the root CA certificate.

Configure FAS

Run the following script to configure FAS:

1 sudo /opt/Citrix/VDA/sbin/ctxfascfg.sh
2 <!--NeedCopy-->

Note:

The preceding script handles only scenarios with a single root CA certificate.

If there are intermediate certificates in your environment, add the intermediate paths to
/etc/krb5.conf as follows:

[realms]
EXAMPLE.COM = {
…
pkinit_anchors = FILE:/etc/pki/CA/certs/root.pem
pkinit_pool = FILE:/etc/pki/CA/certs/intermediate.pem

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 284

Linux Virtual Delivery Agent 1912 LTSR

…
}

Two environment variables are added so that ctxfascfg.sh can be run in silent mode:

• CTX_FAS_ADINTEGRATIONWAY=winbind | sssd | centrify –Denotes the Active Directory

integration method, which equals to CTX_EASYINSTALL_ADINTEGRATIONWAY when
CTX_EASYINSTALL_ADINTEGRATIONWAY is specified. If CTX_EASYINSTALL_ADINTEGRATIONWAY
is not specified, CTX_FAS_ADINTEGRATIONWAY uses its own value setting.

• CTX_FAS_ROOT_CA_PATH=<root_CA_certificate> –Specifies the full path of the root CA cer‑

tificate.

Choose the correct Active Directory integration method and then type the correct path of the root CA
certificate (for example, /etc/pki/CA/certs/root.pem).

The script then installs the krb5‑pkinit and pam_krb5 packages and sets the relevant configuration
files.

Limitation

• FAS supports limited platforms and AD integration methods, see the following matrix:

Winbind SSSD Centrify

RHEL 7.7 /CentOS 7.7 √ √ √

Ubuntu 18.04 √ × √
Ubuntu 16.04 √ × √
SLES 12.3 √ × √

• FAS does not support lock screen yet. If you click the lock button in a session, you cannot log
back on to the session again by using FAS.

• This release supports only the common FAS deployments summarized in the Federated Authen‑
tication Service architectural overview article and does not include Windows 10 Azure AD Join.

Troubleshooting

Before troubleshooting FAS, ensure that the Linux VDA is installed and configured correctly so that a
non‑FAS session can be launched successfully on the common store by using password authentica‑
tion.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 285

Linux Virtual Delivery Agent 1912 LTSR

If non‑FAS sessions work properly, set the HDX log level of the Login class to VERBOSE and the VDA
log level to TRACE. For information on how to enable trace logging for the Linux VDA, see Knowledge
Center article CTX220130.

FAS server configuration error

Launching a session from the FAS store fails. For example, see the following screen capture:

Check /var/log/xdl/hdx.log and find the error log similar to the following:

1 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: query2fas: failed

to retrieve data: No such file or directory.
2
3 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin:
sayhello2fas_internal: Failed to query.
4
5 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin:
sayhello2fas_convertcredential: exit.
6
7 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: LoginFasValidate:
Failed to start FAS.
8
9 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: receive_data:
LoginFASValidate - parameters check error.
10
11 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: receive_data: Exit
FAILURE
12
13 2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: main: EXITING
login process..., FAILURE
14 <!--NeedCopy-->

Solution Run the following command to verify that the Citrix registry value “HKEY_LOCAL_MACHINE\SOFTWARE\
is set to <Your‑FAS‑Server‑List>.

1 sudo /opt/Citrix/VDA/bin/ctxreg dump | grep "UserCredentialService"

2 <!--NeedCopy-->

If the existing setting is incorrect, follow the preceding Set FAS servers step to set it again.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 286

Linux Virtual Delivery Agent 1912 LTSR

Incorrect root CA certificate configuration

Launching a session from the FAS store fails. A gray window appears and disappears several seconds
later.

Check /var/log/xdl/hdx.log and find the error log similar to the following:

1 2018-03-27 10:15:52.227 <P9099:S3> citrix-ctxlogin: validate_user:

pam_authenticate err,can retry for user user1@CTXFAS.LAB
2
3 2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: logout_user:
closing session and pam transaction
4
5 2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: validate_user: Exit
(user=user1@CTXFAS.LAB)=INVALID_PASSWORD
6
7 2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: LoginBoxValidate:
failed validation of user 'user1@CTXFAS.LAB', INVALID_PASSWORD
8
9 2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: Audit_login_failure
: Not yet implemented
10 <!--NeedCopy-->

Solution Verify that the full path of the root CA certificate is set correctly in /etc/krb5.conf. The full
path is similar to the following:

1 [realms]
2
3 EXAMPLE.COM = {
4
5
6 ......
7
8 pkinit_anchors = FILE:/etc/pki/CA/certs/root.pem
9
10 ......
11
12 }
13

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 287

Linux Virtual Delivery Agent 1912 LTSR

14 <!--NeedCopy-->

If the existing setting is incorrect, follow the preceding Install a root CA certificate step to set it again.

Alternatively, check whether the root CA certificate is valid.

Shadow account mapping error

FAS is configured by SAML authentication. The following error might occur after an ADFS user enters
the user name and password on the ADFS logon page.

This error indicates that the ADFS user has been verified successfully, but there is no shadow user
configured on AD.

Solution Set the Shadow Account on AD.

ADFS not configured

The following error occurs during a logon attempt to the FAS store:

The cause is that the FAS store is configured to use SAML authentication while the ADFS deployment
is missing.

Solution Deploy the ADFS IdP for Federated Authentication Service. For more information, see Fed‑
erated Authentication Service ADFS deployment.

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 288

Related information

• The common FAS deployments are summarized in the Federated Authentication Service archi‑
tectural overview article.
• “How‑to”articles are introduced in the Federated Authentication Service advanced configura‑
tion chapter.

Known issue

When FAS is in use, you can fail when trying to launch a published desktop or app session with non‑
English characters.

Workaround

Right‑click Manage Templates in the CA tool to change the Citrix_SmartcardLogon template from
Build from this Active Directory information to Supply in the request:
Linux Virtual Delivery Agent 1912 LTSR

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 290

Linux Virtual Delivery Agent 1912 LTSR

© 2024 Cloud Software Group, Inc. All rights reserved. Cloud Software Group, the Cloud Software Group logo, and other

marks appearing herein are property of Cloud Software Group, Inc. and/or one or more of its subsidiaries, and may be

registered with the U.S. Patent and Trademark Office and in other countries. All other marks are the property of their

respective owner(s).

© 1999–2024 Cloud Software Group, Inc. All rights reserved. 291