Linux Virtual Delivery Agent

Create domain-joined VDAs using easy install

September 26, 2024

Contributed by:

B C

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 configuration files automatically.

To create non-domain joined VDAs, you can use both Machine Creation Services (MCS) and easy install. For more information, see Create non-domain-joined Linux VDAs using MCS and Create a non-domain-joined Linux VDA using easy install (preview).

To learn about the features available for non-domain-joined VDAs, go to Non-domain-joined VDAs.

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.
Active Directory (AD) integration method - Currently, easy install supports SSSD, Winbind, Centrify, PBIS, and Quest. Easy install supports Quest only for RHEL and Rocky Linux.
User name – The name of the user who joins the machine to the domain.
Password - The password of the user who joins the machine to the domain.
OU – The organization unit. Optional.

Important:

To install the Linux VDA, verify that the repositories are added correctly on the Linux machine.

To launch a session, verify that the X Window system and desktop environments are installed.

For security, easy install does not save the domain joining password. Every time you run the easy install script (ctxinstall.sh) in interactive mode, you must enter the domain joining password manually. In silent mode, you must set the domain joining password in /Citrix/VDA/sbin/ctxinstall.conf or export the password. We recommend you not use the administrator account for domain joining. Instead, delegate domain joining permissions to an Active Directory user other than the administrator account. To do so, delegate control on the domain controller using the Delegation of Control Wizard.

Step 2: Prepare the hypervisor

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

Fix time synchronization on XenServer (formerly Citrix Hypervisor)

When the XenServer Time Sync feature is enabled, within each paravirtualized Linux VM you experience issues with NTP and XenServer. Both try to manage the system clock. To avoid the clock becoming out of sync with other servers, make sure 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.

If you are running a paravirtualized Linux kernel with XenServer VM Tools installed, you can check whether the XenServer Time Sync feature is present and enabled from within the Linux VM:

su -

cat /proc/sys/xen/independent_wallclock
<!--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:

sudo echo 1 > /proc/sys/xen/independent_wallclock
<!--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:

su -

cat /proc/sys/xen/independent_wallclock
<!--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 synchronization 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:

Open the Hyper-V Manager console.
For the settings of a Linux VM, select Integration Services.
Ensure that Time synchronization is selected.

Note:

This approach is different from VMware and XenServer (formerly 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 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:

Open the vSphere Client.
Edit settings for the Linux VM.
In the Virtual Machine Properties dialog, open the Options tab.
Select VMware Tools.
In the Advanced box, clear Synchronize guest time with host.

Step 3: Install .NET

In addition to the .NET Runtime, you must install .ASP.NET Core Runtime on all supported Linux distributions before you install or upgrade the Linux VDA. Version 6 is required for Amazon Linux 2. Version 8 is required for other distributions.

If your Linux distribution contains the .NET version that you require, install it from the built-in feed. Otherwise, install .NET from the Microsoft package feed. For more information, see https://docs.microsoft.com/en-us/dotnet/core/install/linux-package-managers.

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

Based on the command output, set the .NET 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.
Expand Components to find the Linux VDA. For example:
Click the Linux VDA link to access the Linux VDA downloads.
Download the Linux VDA package that matches your Linux distribution.
Download the GPG public key that you can use to verify the integrity of the Linux VDA package. For example:

To verify the integrity of the Linux VDA package by using the public key:
- For an RPM package, run the following commands to import the public key into the RPM database and to check the package integrity:
```
 rpmkeys --import <path to the public key>
 rpm --checksig --verbose <path to the Linux VDA package>
 
```
- For a DEB package, run the following commands to import the public key into the DEB database and to check the package integrity:
```
 sudo apt-get install dpkg-sig
 gpg --import <path to the public key>
 dpkg-sig --verify <path to the Linux VDA package>
 
```

Step 5: Install the Linux VDA package

To set up the environment for the Linux VDA, run the following commands.

For Amazon Linux 2, CentOS, RHEL, and Rocky Linux distributions:

Note:

For RHEL and CentOS, install the EPEL repository before you can install the Linux VDA successfully. For information on how to install EPEL, see the instructions at https://docs.fedoraproject.org/en-US/epel/.

Before installing the Linux VDA on RHEL 9.4/9.2 and Rocky Linux 9.4/9.2, update the libsepol package to version 3.4 or later.

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

Note:

After you install the Linux VDA on RHEL 8.x/9.x and Rocky Linux 8.x/9.x hosted on GCP, the Ethernet connection might be lost and the Linux VDA might be unreachable after a VM restart. To work around the issue, set a root password when logging on to the VM for the first time and make sure that you can log on to the VM as root. Then, run the following commands in the console after restarting the VM:
nmcli dev connect eth0
systemctl restart NetworkManager

For Ubuntu/Debian distributions:

sudo dpkg -i <PATH>/<Linux VDA deb>
sudo apt-get install -f
<!--NeedCopy-->

Note:

To install the necessary dependencies for a Debian 11 distribution, add the deb http://deb.debian.org/debian/ bullseye main line to the /etc/apt/sources.list file.

For Ubuntu 24.04, 22.04, 20.04 on GCP, disable RDNS. To do so, add the rdns = false line under [libdefaults] in /etc/krb5.conf.

For SUSE distributions:

For SUSE 15.6 on AWS, Azure, and GCP, ensure that:
- You are using libstdc++6 version 12 or later.
- The Default_WM parameter in /etc/sysconfig/windowmanager is set to “gnome”.

Run the following command to install the Linux VDA:

zypper -i install <PATH>/<Linux VDA RPM>
<!--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 hypervisors, see the following guides:

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

Ensure that the guest VM is shut down.
In the hypervisor control panel, allocate a GPU to the VM.
Start the VM.
Install the guest VM driver on the VM.

Step 7: Specify a database to use

You can switch between SQLite and PostgreSQL after installing the Linux VDA package. To do so, complete the following steps:

Note:

We recommend you use SQLite for VDI mode only and use PostgreSQL for a hosted shared desktops delivery model.

For easy install and MCS, you can specify SQLite or PostgreSQL to use without having to install them manually. Unless otherwise specified through /etc/xdl/db.conf, the Linux VDA uses PostgreSQL by default. If you require a custom version of PostgreSQL instead of the version provided by your Linux distribution, you must install the specified version manually, edit /etc/xdl/db.conf to reflect the new version, and start the PostgreSQL service before running the easy install script (ctxinstall.sh) or the MCS script (deploymcs.sh).

You can also use /etc/xdl/db.conf to configure the port number for PostgreSQL.

(Optional) To use a custom version of PostgreSQL instead of the version provided by your Linux distribution, install the specified version manually and start the PostgreSQL service.

Edit /etc/xdl/db.conf to specify a database to use. The following is an example db.conf file:

# database configuration file for Linux VDA

## database choice
# possible choices are:
#     SQLite
#     PostgreSQL
# default choice is PostgreSQL
DbType="PostgreSQL"


## database port
# specify database port for the database.
# if not specified, default port will be used:
# SQLite: N/A
# PostgreSQL: 5432
DbPort=5432


## PostgreSQL customized
# only the following value means true, otherwise false:
#     true
#     yes
#     y
#     YES
#     Y
# default is false
DbCustomizePostgreSQL=false

## PostgreSQL service name
# specify the service name of PostgreSQL for Linux VDA
# default is "postgresql"
DbPostgreSQLServiceName="postgresql"
<!--NeedCopy-->

To use a custom version of PostgreSQL, set DbCustomizePostgreSQL to true.

Run sudo /opt/Citrix/VDA/sbin/ctxinstall.sh or /opt/Citrix/VDA/bin/easyinstall.

Step 8: Run easy install to configure the environment and VDA to complete the installation

After installing the Linux VDA package, configure the running environment by using the ctxinstall.sh script or GUI.

Note:

Before setting up the runtime environment, ensure that the en_US.UTF-8 locale is installed in your OS. If the locale is not available in your OS, run the sudo locale-gen en_US.UTF-8 command. For Debian, edit the /etc/locale.gen file by uncommenting the # en_US.UTF-8 UTF-8 line and then run the sudo locale-gen command.

ctxinstall.sh

ctxinstall.sh is the easy install script for doing some pre-configuration and setting up the VDA running environment variables.

Only root can run this script.
Easy install uses /opt/Citrix/VDA/sbin/ctxinstall.conf as its configuration file to set, save, and synchronize the values of all environment variables used. We recommend you read the template (ctxinstall.conf.tmpl) carefully and then customize your own ctxinstall.conf. When you first create the configuration file, use either of the following ways:
- By copying the /opt/Citrix/VDA/sbin/ctxinstall.conf.tmpl template file and saving it as /opt/Citrix/VDA/sbin/ctxinstall.conf.
- By running ctxinstall.sh. Each time you run ctxinstall.sh, your input is saved in /opt/Citrix/VDA/sbin/ctxinstall.conf.
Easy install supports modular running. Modules include pre-check, installation, domain-configuration, setup, and verification.
Debugging details for this script can be found in /var/log/xdl/ctxinstall.log.

For more information, use the help command ctxinstall.sh -h.

Note:

Following the principle of least privilege, ensure that only the root user can read /opt/Citrix/VDA/sbin/ctxinstall.conf because the domain joining password might be set in the file.

Uninstalling the Linux VDA removes files under /opt/Citrix/VDA. We recommend you back up /opt/Citrix/VDA/sbin/ctxinstall.conf before uninstalling the VDA.

You can run ctxinstall.sh in interactive mode or silent mode. Before you run the script, set the following environment variables:

CTX_XDL_NON_DOMAIN_JOINED=’y|n’ – Whether to join the machine to a domain. The default value is ‘n’. For domain-joined scenarios, set it to ‘n’.
CTX_XDL_AD_INTEGRATION=’sssd|winbind|centrify|pbis|quest’ – 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.
CTX_XDL_DDC_LIST=’<list-ddc-fqdns>‘ – The Linux VDA requires a space-separated list of Delivery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Controller. At least one FQDN or CNAME must be specified.
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_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_START_SERVICE=’y|n’ – Determines whether the Linux VDA services are started when the configuration is complete.
CTX_XDL_REGISTER_SERVICE=’y|n’ – The Linux Virtual Desktop services are started after machine startup.
CTX_XDL_ADD_FIREWALL_RULES=’y|n’ – The Linux VDA services require incoming network connections to be allowed through the system firewall. You can open the required ports (by default ports 80 and 1494) automatically in the system firewall for the Linux Virtual Desktop.
CTX_XDL_DESKTOP_ENVIRONMENT=gnome/gnome-classic/kde/mate/xfce/’<none>‘ – Specifies the GNOME, GNOME Classic, KDE, MATE, or Xfce desktop environment to use in sessions. If you set it to ‘<none>‘, the default desktop configured on the VDA is used.
CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime – The path to install .NET for supporting the new broker agent service (ctxvda). The default path is ‘/usr/bin’.
CTX_XDL_VDA_PORT=port-number – The Linux VDA communicates with Delivery Controllers through a TCP/IP port.
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 ad2.mycompany.com:3268 ad3.mycompany.com:3268. To enable faster LDAP queries within an Active Directory forest, enable Global Catalog on a domain controller and specify the relevant LDAP port number as 3268. 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). If unnecessary, set to ‘<none>‘.
CTX_XDL_SUPPORT_DDC_AS_CNAME=’y|n’ – The Linux VDA supports specifying a Delivery Controller name using a DNS CNAME record.
CTX_EASYINSTALL_DNS=’<ip-address-of-dns>‘ – The IP address of DNS.
CTX_EASYINSTALL_HOSTNAME=host-name – The host name of the Linux VDA server.
CTX_EASYINSTALL_NTPS=address-of-ntps – The IP address or string name of the NTP server.
CTX_EASYINSTALL_REALM=realm-name – The Kerberos realm name.
CTX_EASYINSTALL_FQDN=ad-fqdn-name
CTX_EASYINSTALL_USERNAME=domain-user-name – The name of the user who joins the machine to the domain.
CTX_EASYINSTALL_PASSWORD=password – The password of the user who joins the machine to the domain.

Note:

We recommend you not use the administrator account for domain joining. Instead, delegate domain joining permissions to an Active Directory user other than the administrator account. To do so, delegate control on the domain controller using the Delegation of Control Wizard.

The following four variables are optional. Even if they are not set, ctxinstall.sh won’t abort in silent mode and you won’t be prompted for user input in interactive mode. You can set them only by exporting their values or editing /Citrix/VDA/sbin/ctxinstall.conf.

CTX_EASYINSTALL_NETBIOS_DOMAIN=netbios-domain-name – The NetBIOS domain name is typically the first component of the DNS domain name separated by a dot (.). Otherwise, customize a different NetBIOS domain name. This variable is optional.
CTX_EASYINSTALL_OU=ou-value – OU values vary with different AD integration methods. For an example of OU values, see the table in the Considerations section of this article. This variable is optional.
CTX_EASYINSTALL_CENTRIFY_LOCAL_PATH=centrify-local-path – Easy install helps download the Centrify package from the Internet. However, if Centrify is already installed, you can fetch the Centrify package from a local directory defined by this variable. This variable is optional.
CTX_EASYINSTALL_PBIS_LOCAL_PATH= pbis-local-path – Easy install helps download the PBIS package from the Internet. However, if PBIS is already installed, you can fetch the PBIS package from a local directory defined by this variable. This variable is optional.

Considerations

The NetBIOS domain name is typically the first component of the DNS domain name separated by a dot (.). To customize a different NetBIOS domain name in your environment, set the environment variable CTX_EASYINSTALL_NETBIOS_DOMAIN in /opt/Citrix/VDA/sbin/ctxinstall.conf.

To join your VDA to a specific OU, do the following:

Ensure that the specific OU exists on the domain controller.

For an example OU, see the following screen capture:

Set the environment variable CTX_EASYINSTALL_OU in /opt/Citrix/VDA/sbin/ctxinstall.conf.

OU values vary with different AD methods. The following table reflects the example OU names in the preceding screen capture. You can use any other OU names in your organization.

OS	Winbind	SSSD	Centrify	PBIS
Amazon Linux 2	`"Linux/amazon"`	`"Linux/amazon"`	`"XD.LOCAL/Linux/amazon"`	`"Linux/amazon"`
Debian	`"Linux/debian"`	`"Linux/debian"`	`"XD.LOCAL/Linux/debian"`	`"Linux/debian"`
RHEL 9.4/9.2, Rocky Linux 9.4/9.2	`"OU=redhat,OU=Linux"`	`"OU=redhat,OU=Linux"`	N/A	N/A
RHEL 8.x	`"OU=redhat,OU=Linux"`	`"OU=redhat,OU=Linux"`	`"XD.LOCAL/Linux/redhat"`	`"Linux/redhat"`
Rocky Linux 8.x	`"OU=redhat,OU=Linux"`	`"OU=redhat,OU=Linux"`	N/A	N/A
SUSE	`"Linux/suse"`	`"Linux/suse"`	`"XD.LOCAL/Linux/suse"`	`"Linux/suse"`
Ubuntu	`"Linux/ubuntu"`	`"Linux/ubuntu"`	`"XD.LOCAL/Linux/ubuntu"`	`"Linux/ubuntu"`

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:
```
 ADSITE   : Check that this machine's subnet is in a site known by AD   : Failed
          : This machine's subnet is not known by AD.
          : We guess you should be in the site Site1.
 
```
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.
Easy install supports pure IPv6 starting with the Linux VDA 7.16. The following preconditions and limitations apply:
- Your Linux repository must be configured to ensure that your machine can download the required 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 configuration, the type of the first DNS IP address determines whether IPv4 or IPv6 is used for registration.
You can specify a desktop environment to use in sessions by using the CTX_XDL_DESKTOP_ENVIRONMENT variable as described earlier. You can also switch between desktop environments by running commands or using the system tray. For more information, see Desktop switching commands and System tray.

If you choose Centrify as the method to join a domain, the ctxinstall.sh script requires the Centrify package. 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:

Amazon Linux 2/RHEL: wget https://downloads.centrify.com/products/server-suite/2022/component-update-1/delinea-server-suite-2022-rhel6-x86_64.tgz

CentOS: wget https://downloads.centrify.com/products/server-suite/2022/component-update-1/delinea-server-suite-2022-rhel6-x86_64.tgz

SUSE: wget https://downloads.centrify.com/products/server-suite/2022/component-update-1/delinea-server-suite-2022-suse12-x86_64.tgz

Ubuntu/Debian: wget https://downloads.centrify.com/products/server-suite/2022/component-update-1/delinea-server-suite-2022-deb9-x86_64.tgz

Fetch the Centrify package from a local directory if Centrify is already installed. To designate the directory of the Centrify package, set CTX_EASYINSTALL_CENTRIFY_LOCAL_PATH=/home/mydir in /opt/Citrix/VDA/sbin/ctxinstall.conf. For example:

 ls  -ls  /home/mydir
     9548 -r-xr-xr-x. 1 root root  9776688 May 13  2016 adcheck-rhel4-x86_64
     4140 -r--r--r--. 1 root root  4236714 Apr 21  2016 centrifyda-3.3.1-rhel4-x86_64.rpm
     33492 -r--r--r--. 1 root root 34292673 May 13  2016 centrifydc-5.3.1-rhel4-x86_64.rpm
     4 -rw-rw-r--. 1 root root     1168 Dec  1  2015 centrifydc-install.cfg
     756 -r--r--r--. 1 root root   770991 May 13  2016 centrifydc-ldapproxy-5.3.1-rhel4-x86_64.rpm
     268 -r--r--r--. 1 root root   271296 May 13  2016 centrifydc-nis-5.3.1-rhel4-x86_64.rpm
     1888 -r--r--r--. 1 root root  1930084 Apr 12  2016 centrifydc-openssh-7.2p2-5.3.1-rhel4-x86_64.rpm
     124 -rw-rw-r--. 1 root root   124543 Apr 19  2016 centrify-suite.cfg
     0 lrwxrwxrwx. 1 root root       10 Jul  9  2012 install-express.sh -> install.sh
     332 -r-xr-xr--. 1 root root   338292 Apr 10  2016 install.sh
     12 -r--r--r--. 1 root root    11166 Apr  9  2015 release-notes-agent-rhel4-x86_64.txt
     4 -r--r--r--. 1 root root     3732 Aug 24  2015 release-notes-da-rhel4-x86_64.txt
     4 -r--r--r--. 1 root root     2749 Apr  7  2015 release-notes-nis-rhel4-x86_64.txt
     12 -r--r--r--. 1 root root     9133 Mar 21  2016 release-notes-openssh-rhel4-x86_64.txt
 <!--NeedCopy-->

If you choose PBIS as the method to join a domain, the ctxinstall.sh script requires the PBIS package. Ways for ctxinstall.sh to get the PBIS package:
- Easy install helps download the PBIS package from the Internet automatically. For example, the following are the URLs for each distribution:
  
  Amazon Linux 2, RHEL 8, SUSE 15.6: wget https://github.com/BeyondTrust/pbis-open/releases/download/9.1.0/pbis-open-9.1.0.551.linux.x86_64.rpm.sh
  
  Debian, Ubuntu: wget https://github.com/BeyondTrust/pbis-open/releases/download/9.1.0/pbis-open-9.1.0.551.linux.x86_64.deb.sh
- Fetch a specific version of the PBIS package from the Internet. To do so, change the “pbisDownloadRelease” and “pbisDownloadExpectedSHA256” lines in the /opt/Citrix/VDA/sbin/ctxinstall.sh file.
  
  For an example, see the following screen capture:
- Fetch the PBIS package from a local directory if PBIS is already installed. To designate the directory of the PBIS package, set the environment variable CTX_EASYINSTALL_PBIS_LOCAL_PATH in /opt/Citrix/VDA/sbin/ctxinstall.conf.

Interactive mode

To run the ctxinstall.sh script in interactive mode, use the sudo /opt/Citrix/VDA/sbin/ctxinstall.sh command without the -S option. Type the relevant variable value at each prompt in the command-line interface. If a variable is already set, ctxinstall.sh asks for confirmation in case you want to change it.

Silent mode

In silent mode, you must set the preceding variables by using /opt/Citrix/VDA/sbin/ctxinstall.conf or the export command. After that, run ctxinstall.sh -S (note that the letter S here is in uppercase). If not all required variables are set or some value is invalid, ctxinstall.sh aborts execution, unless there are default values.

The exported value for each variable overwrites the value in /Citrix/VDA/sbin/ctxinstall.conf, unless it is not set. All updated values are saved in /Citrix/VDA/sbin/ctxinstall.conf, except the domain joining password. So in silent mode, you must set the domain joining password in /Citrix/VDA/sbin/ctxinstall.conf or export the password.

export CTX_XDL_NON_DOMAIN_JOINED='n'
export CTX_XDL_AD_INTEGRATION=sssd|winbind|centrify|pbis|quest
export CTX_XDL_DDC_LIST='<list-ddc-fqdns>'
export CTX_XDL_VDI_MODE='y|n'
export CTX_XDL_HDX_3D_PRO='y|n'
export CTX_XDL_START_SERVICE='y|n'
export CTX_XDL_REGISTER_SERVICE='y|n'
export CTX_XDL_ADD_FIREWALL_RULES='y|n'
export CTX_XDL_DESKTOP_ENVIRONMENT=gnome|gnome-classic|kde|mate|xfce|'<none>'
export CTX_XDL_DOTNET_RUNTIME_PATH='<path-to-install-dotnet-runtime>'
export CTX_XDL_VDA_PORT='<port-number>'
export CTX_XDL_SITE_NAME='<dns-site-name>'|'<none>'
export CTX_XDL_LDAP_LIST='<list-ldap-servers>'|'<none>'
export CTX_XDL_SEARCH_BASE='<search-base-set>'|'<none>'
export CTX_XDL_SUPPORT_DDC_AS_CNAME='y|n'
export CTX_EASYINSTALL_DNS='<ip-address-of-dns>'
export CTX_EASYINSTALL_HOSTNAME='<host-name>'
export CTX_EASYINSTALL_NTPS='<address-of-ntps>'
export CTX_EASYINSTALL_REALM='<realm-name>'
export CTX_EASYINSTALL_FQDN='<ad-fqdn-name>'
export CTX_EASYINSTALL_USERNAME='<domain-user-name>'
export CTX_EASYINSTALL_PASSWORD='<password>'
export CTX_EASYINSTALL_NETBIOS_DOMAIN='<netbios-domain>'
export CTX_EASYINSTALL_OU='<organization-unit>'
sudo -E /opt/Citrix/VDA/sbin/ctxinstall.sh -S
<!--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 variables by using a single command.

To set up the VDA running environment variables (those beginning with ‘CTX_XDL_’), you can run ctxinstall.sh -s (note that the letter s here is in lowercase).

GUI

You can use easy install through a GUI. Run the /opt/Citrix/VDA/bin/easyinstall command in the desktop environment of your VDA and then follow the instructions on the easy install GUI.

Easy install GUI

The easy install GUI guides you through the following operations:

Check the system environment
Install dependencies
Join the VDA to a specified domain
Configure the runtime environment

Tip:

Click Save to save variable settings to a local file under the path you specify. Click Load to load variable settings from a file that you specify. For information on configuring MCS variables, see Step 3: Prepare a master image.

Step 9: Run XDPing

Run sudo /opt/Citrix/VDA/bin/xdping to check for common configuration issues with a Linux VDA environment. For more information, see XDPing.

Step 10: Run the Linux VDA

Start the Linux VDA:

To start the Linux VDA services:

sudo systemctl start ctxhdx.service

sudo systemctl start ctxvda.service
<!--NeedCopy-->

Stop the Linux VDA:

To stop the Linux VDA services:

sudo systemctl stop ctxvda.service

sudo systemctl stop ctxhdx.service
<!--NeedCopy-->

Note:

Before you stop the ctxvda and ctxhdx services, run the systemctl stop ctxmonitord 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:

sudo systemctl stop ctxvda.service

sudo systemctl restart ctxhdx.service

sudo systemctl start ctxvda.service
<!--NeedCopy-->

Check the status of the Linux VDA:

To check the running status of the Linux VDA services:

sudo systemctl status ctxvda.service

sudo systemctl status ctxhdx.service
<!--NeedCopy-->

Step 11: Create machine catalogs

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 differentiate 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 delivery 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 delivery groups

The process for creating a delivery group and adding machine catalogs containing Linux VDA machines is almost identical to Windows VDA machines. For a more detailed description of how to complete these tasks, see Create delivery groups.

For creating delivery groups that contain Linux VDA machine catalogs, the following restrictions apply:

Ensure that the AD users and groups that 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 2407.

Step 13: Upgrade the Linux VDA (optional)

The Linux VDA supports upgrades from the most recent version. For example, you can upgrade the Linux VDA from 2308 to 2311 and from 1912 LTSR to 2203 LTSR.

Note:
Upgrading an existing installation overwrites the configuration files under /etc/xdl. Before you conduct an upgrade, make sure to back up the files.
Starting with the 2407 release, the Linux VDA delegates package managers rpm or dpkg to handle configuration files during upgrades. The following describes how rpm and dpkg interact with changes to configuration files:
rpm: by default keeps the local version and saves the new version from the package with a .rpmnew extension.
dpkg: interactively prompts you with a choice on how to proceed. To silently upgrade the Linux VDA while retaining your local configuration file and saving the new package version as .dpkg-new or .dpkg-dist, use the following command:
 dpkg --force-confold -i package.deb  # Always keep your version, then save new package's version as *.dpkg-new or *.dpkg-dist

For Amazon Linux 2, RHEL, and Rocky Linux distributions:

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

Note:

Before upgrading the Linux VDA on RHEL 9.4/9.2 and Rocky Linux 9.4/9.2, update the libsepol package to version 3.4 or later.

For SUSE distributions:

sudo zypper -i install <PATH>/<Linux VDA RPM>
<!--NeedCopy-->

For Ubuntu/Debian distributions:

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

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

Troubleshooting

Use the information in this section to troubleshoot issues that can arise from using the easy install 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):

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:

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)'.
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))
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')
Check the following:- The system clock is in sync between this machine and the delivery controller.
-  The Active Directory provider (e.g. winbind daemon) service is running and correctly configured.
-  Kerberos is correctly configured on this machine.
If the problem persists, please refer to Citrix Knowledge Base article CTX117248 for further information.
Error Details:
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'.
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.
Ensure that the system clock is in sync between this machine and the delivery controller.
Verify the NTP daemon is running on this machine and is correctly configured.
2016-11-04 02:11:52.364 [ERROR] - Could not register with any controllers. Waiting to try again in 120000 ms. Multi-forest - false
2016-11-04 02:11:52.365 [INFO ] - The Citrix Desktop Service failed to register with any controllers in the last 470 minutes.
<!--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:

Run the rm -f /etc/krb5.keytab command.
Run the net ads leave $REALM -U $domain-administrator command.
Remove the machine catalog and delivery group on the Delivery Controller.
Run /opt/Citrix/VDA/sbin/ctxinstall.sh.
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:

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

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

/var/log/xdl/hdx.log:

2016-11-02 13:21:19.015 <P22492:S1> citrix-ctxlogin: StartUserSession: failed to change to directory(/home/CITRIXLAB/ctxadmin) errno(2)

2016-11-02 13:21:19.017 <P22227> citrix-ctxhdx: logSessionEvent: Session started for user ctxadmin.

2016-11-02 13:21:19.023 <P22492:S1> citrix-ctxlogin: ChildPipeCallback: Login Process died: normal.

2016-11-02 13:21:59.217 <P22449:S1> citrix-ctxgfx: main: Exiting normally.
<!--NeedCopy-->

Tip:

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

To resolve this issue:

From a command line, type pam-auth-update.
In the resulting dialog, verify that Create home directory login is selected.

Session does not launch or ends quickly with dbus error

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

Oct 27 04:17:16 CentOS7 citrix-ctxhdx[8978]: Session started for user CITRIXLAB\ctxadmin.

Oct 27 04:17:18 CentOS7 kernel: traps: gnome-session[19146] trap int3 ip:7f89b3bde8d3 sp:7fff8c3409d0 error:0

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

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)

Oct 27 04:17:18 CentOS7 gnome-session: aborting...

Oct 27 04:17:18 CentOS7 citrix-ctxgfx[18981]: Exiting normally.

Oct 27 04:17:18 CentOS7 citrix-ctxhdx[8978]: Session stopped for user CITRIXLAB\ctxadmin.
<!--NeedCopy-->

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

Nov  3 11:03:52 user01-HVM-domU pulseaudio[25326]: [pulseaudio] pid.c: Stale PID file, overwriting.

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.

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.

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.

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

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
<!--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/xdl/ctxinstall.log:

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

Jan 25 23:30:31 yz-rhel72-1 python[3945]: SELinux is preventing /usr/sbin/sshd from setattr access on the directory /root.

*****  Plugin catchall_boolean (89.3 confidence) suggests   ******************

If you want to allow polyinstantiation to enabled

   Then you must tell SELinux about this by enabling the 'polyinstantiation_enabled' boolean.

You can read 'None' man page for more details.

    Do

       setsebool -P polyinstantiation_enabled 1

*****  Plugin catchall (11.6 confidence) suggests   **************************

If you believe that sshd should be allowed setattr access on the root directory by default.

Then you should report this as a bug.

You can generate a local policy module to allow this access.

      Do

       allow this access for now by executing:

       # grep sshd /var/log/audit/audit.log | audit2allow -M mypol

# semodule -i mypol.pp
<!--NeedCopy-->

To resolve this issue:

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

SELINUX=disabled
Restart the VDA.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Create domain-joined VDAs using easy install

September 26, 2024

Contributed by:

B C

September 26, 2024

Contributed by:

B C

Step 1: Prepare configuration information and the Linux machine
Step 2: Prepare the hypervisor
Step 3: Install .NET
Step 4: Download the Linux VDA package
Step 5: Install the Linux VDA package
Step 6: Install NVIDIA GRID drivers
Step 7: Specify a database to use
Step 8: Run easy install to configure the environment and VDA to complete the installation
- ctxinstall.sh
- GUI
Step 9: Run XDPing
Step 10: Run the Linux VDA
Step 11: Create machine catalogs
Step 12: Create delivery groups
Step 13: Upgrade the Linux VDA (optional)
Troubleshooting

Was this helpful

Create domain-joined VDAs using easy install

Step 1: Prepare configuration information and the Linux machine

Step 2: Prepare the hypervisor

Fix time synchronization on XenServer (formerly Citrix Hypervisor)

Fix time synchronization on Microsoft Hyper-V

Fix time synchronization on ESX and ESXi

Step 3: Install .NET

Step 4: Download the Linux VDA package

Step 5: Install the Linux VDA package

Step 6: Install NVIDIA GRID drivers

Step 7: Specify a database to use

Step 8: Run easy install to configure the environment and VDA to complete the installation

ctxinstall.sh

Considerations

Interactive mode

Silent mode

GUI

Step 9: Run XDPing

Step 10: Run the Linux VDA

Step 11: Create machine catalogs

Step 12: Create delivery groups

Step 13: Upgrade the Linux VDA (optional)

Troubleshooting

Joining a domain by using SSSD fails

Ubuntu desktop sessions show a gray screen

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

Session does not launch or ends quickly with dbus error

SELinux prevents SSHD from accessing the home directory

In this article