Install Linux Virtual Delivery Agent for Amazon Linux 2, CentOS, and RHEL manually

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 your Linux distribution 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 to contain only the host name of the machine.

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

hostname
<!--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:

hostname -f
<!--NeedCopy-->

This command returns the FQDN of the machine.

Step 1e: Check name resolution and service reachability

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

nslookup domain-controller-fqdn

ping domain-controller-fqdn

nslookup delivery-controller-fqdn

ping delivery-controller-fqdn
<!--NeedCopy-->

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

Step 1f: Configure clock synchronization

Maintaining accurate clock synchronization between the VDAs, Delivery Controllers, and domain controllers 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.

An RHEL 8/RHEL 7 default environment uses the Chrony daemon (chronyd) for clock synchronization.

Configure the Chrony service

As a root user, edit /etc/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
<!--NeedCopy-->

In a typical deployment, synchronize time from the local domain controllers and not directly from public 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:

sudo /sbin/service chronyd restart
<!--NeedCopy-->

Step 1g: Install OpenJDK 11

The Linux VDA requires the presence of OpenJDK 11.

• If you are using CentOS or RHEL, OpenJDK 11 is automatically installed as a dependency when you install the Linux VDA.

• If you are using Amazon Linux 2, run the following command to enable and install OpenJDK 11:

   amazon-linux-extras install java-openjdk11
   <!--NeedCopy-->
  

Confirm the correct version:

sudo yum info java-11-openjdk
<!--NeedCopy-->

The prepackaged OpenJDK might be an earlier version. Update to OpenJDK 11:

sudo yum -y update java-11-openjdk
<!--NeedCopy-->

Step 1h: Install PostgreSQL

The Linux VDA requires either PostgreSQL 10.5 or later on RHEL 8 or PostgreSQL 9.2 or later on RHEL 7.

Install the following packages:

sudo yum -y install postgresql-server

sudo yum -y install postgresql-jdbc
<!--NeedCopy-->

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

sudo postgresql-setup initdb
<!--NeedCopy-->

Step 1i: Start PostgreSQL

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

sudo systemctl enable postgresql

sudo systemctl start postgresql
<!--NeedCopy-->

Check the version of PostgreSQL by using:

psql --version
<!--NeedCopy-->

(RHEL 7 only) Verify that the data directory is set by using the psql command-line utility:

sudo -u postgres psql -c 'show data_directory'
<!--NeedCopy-->

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

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:

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) domain:

• Samba Winbind
• Quest Authentication Services
• Centrify DirectControl
• SSSD
• PBIS

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:

For CentOS 8 and RHEL 8:

sudo yum -y install samba-winbind samba-winbind-clients krb5-workstation oddjob-mkhomedir realmd authselect
<!--NeedCopy-->

For Amazon Linux 2, CentOS 7, and RHEL 7:

sudo yum -y install samba-winbind samba-winbind-clients krb5-workstation authconfig oddjob-mkhomedir
<!--NeedCopy-->

Enable Winbind daemon to start upon machine startup

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

sudo /sbin/chkconfig winbind on
<!--NeedCopy-->

Configure Winbind Authentication

Configure the machine for Kerberos authentication by using Winbind:

1. Run the following command.

   For RHEL 8:

   sudo authselect select winbind with-mkhomedir --force
   <!--NeedCopy-->
   

   For Amazon Linux 2 and RHEL 7:

   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
   <!--NeedCopy-->
   

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

   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 machine yet being joined to the domain.

2. 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
winbind offline logon = no

3. (RHEL 8 only) Open /etc/krb5.conf and add entries under the [libdefaults], [realms], and [domain_realm] sections:

   Under the [libdefaults] section:

   default_ccache_name = FILE:/tmp/krb5cc_%{uid}
default_realm = REALM dns_lookup_kdc = true

   Under the [realms] section:

   REALM = {
kdc = fqdn-of-domain-controller
}

   Under the [domain_realm] section:

   realm = REALM
.realm = REALM

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 Directory user account with permissions to add computers to the domain:

For RHEL 8:

sudo realm join -U user --client-software=winbind REALM
<!--NeedCopy-->

For Amazon Linux 2 and RHEL 7:

sudo net ads join REALM -U user
<!--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:

sudo /sbin/service winbind restart
<!--NeedCopy-->

Tip:

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

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:

sudo net ads testjoin
<!--NeedCopy-->

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

sudo net ads info
<!--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:

sudo klist -ke
<!--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 controller using these keys:

sudo kinit -k MACHINE\$@REALM
<!--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:

sudo klist
<!--NeedCopy-->

Examine the account details of the machine using:

sudo net ads status
<!--NeedCopy-->

Verify user authentication

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

wbinfo --krb5auth=domain\\username%password
<!--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 message 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.

ssh localhost -l domain\\username
id -u
<!--NeedCopy-->

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

klist
<!--NeedCopy-->

Exit the session.

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

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

reboot
<!--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. Authentication (offline logon) must be disabled.

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

sudo /opt/quest/bin/vastool configure vas vas_auth allow-disconnected-auth false
<!--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 configure PAM and NSS manually:

sudo /opt/quest/bin/vastool configure pam

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

Join Windows domain

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

sudo /opt/quest/bin/vastool -u user join domain-name
<!--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:

sudo /opt/quest/bin/vastool info domain
<!--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.

ssh localhost -l domain\\username
id -u
<!--NeedCopy-->

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

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

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

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

Exit the session.

exit
<!--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 a Windows domain

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

su –
adjoin -w -V -u user domain-name
<!--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:

su –
adinfo
<!--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:

adinfo --sysinfo all
adinfo –diag
<!--NeedCopy-->

Test connectivity to the various Active Directory and Kerberos services.

adinfo --test
<!--NeedCopy-->

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

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. Enable SSSD
4. Verify the Kerberos configuration
5. Verify user authentication

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.

This section describes the Samba approach for Amazon Linux 2 and RHEL 7 and the adcli approach for RHEL 8. For realmd, see the RHEL or CentOS documentation. These steps must be followed before configuring SSSD.

• Samba (Amazon Linux 2 and RHEL 7):

  Install or update the required packages:

   sudo yum -y install krb5-workstation authconfig oddjob-mkhomedir samba-common-tools
   <!--NeedCopy-->
  

  On the Linux client with properly configured files:

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

  Configure the machine for Samba and Kerberos authentication:

   sudo authconfig --smbsecurity=ads --smbworkgroup=domain --smbrealm=REALM --krb5realm=REALM --krb5kdc=fqdn-of-domain-controller --update
   <!--NeedCopy-->
  

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

  Note:

  Settings in this article are meant for the single-domain, single-forest model. Configure Kerberos based on your AD infrastructure.

  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
winbind offline logon = no

  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:

   sudo net ads join REALM -U user
   <!--NeedCopy-->
  

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

• Adcli (RHEL 8):

  Install or update the required packages:

   sudo yum -y install samba-common samba-common-tools krb5-workstation authconfig oddjob-mkhomedir realmd oddjob authselect
   <!--NeedCopy-->
  

  Configure the machine for Samba and Kerberos authentication:

   sudo authselect select sssd with-mkhomedir --force
   <!--NeedCopy-->
  

  Open /etc/krb5.conf and add the entries under the [realms] and [domain_realm] sections.

  Under the [realms] section:

  REALM = {
kdc = fqdn-of-domain-controller
}

  Under the [domain_realm] section:

  realm = REALM .realm = REALM

  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:

   sudo realm join REALM -U user
   <!--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 by running the sudo yum -y install sssd command.
• Make configuration changes to various files (for example, sssd.conf).
• Start the sssd service.

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

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

(RHEL 8 only) Open /etc/sssd/sssd.conf and add the following entries under the [domain/ad.example.com] section:

ad_gpo_access_control = permissive
full_name_format = %2$s\%1$s
fallback_homedir = /home/%d/%u
# Kerberos settings
krb5_ccachedir = /tmp
krb5_ccname_template = FILE:%d/krb5cc_%U

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

Enable SSSD

For RHEL 8:

Run the following commands to enable SSSD:

sudo systemctl restart sssd
sudo systemctl enable sssd.service
sudo chkconfig sssd on
<!--NeedCopy-->

For Amazon Linux 2, CentOS 7, and RHEL 7:

Use authconfig to enable SSSD. Install oddjob-mkhomedir to ensure that the home directory creation is compatible with SELinux:

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

sudo service sssd start

sudo chkconfig sssd on
<!--NeedCopy-->

Verify Kerberos configuration

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

sudo klist -ke
<!--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 controller using these keys:

sudo kinit –k MACHINE\$@REALM
<!--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:

sudo klist
<!--NeedCopy-->

Verify user authentication

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

sudo getent passwd DOMAIN\\username
<!--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.

sudo ssh localhost –l DOMAIN\\username

id -u
<!--NeedCopy-->

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

ls /tmp/krb5cc_{uid}
<!--NeedCopy-->

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

klist
<!--NeedCopy-->

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

PBIS

Download the required PBIS package

For CentOS 7 and RHEL 7, for example:

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

For Amazon Linux 2, CentOS 8, and RHEL 8, for example:

wget https://github.com/BeyondTrust/pbis-open/releases/download/9.1.0/pbis-open-9.1.0.551.linux.x86_64.rpm.sh
<!--NeedCopy-->

Make the PBIS installation script executable

For CentOS 7 and RHEL 7, for example:

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

For Amazon Linux 2, CentOS 8, and RHEL 8, for example:

chmod +x pbis-open-9.1.0.551.linux.x86_64.rpm.sh
<!--NeedCopy-->

Run the PBIS installation script

For CentOS 7 and RHEL 7, for example:

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

For Amazon Linux 2, CentOS 8, and RHEL 8, for example:

sh pbis-open-9.1.0.551.linux.x86_64.rpm.sh
<!--NeedCopy-->

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:

/opt/pbis/bin/domainjoin-cli join domain-name user
<!--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:

/opt/pbis/bin/domainjoin-cli query
<!--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.

ssh localhost -l domain\\user

id -u
<!--NeedCopy-->

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

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

Exit the session.

exit
<!--NeedCopy-->

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

Step 4: Install .NET Core Runtime 3.1 as a prerequisite

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

After installing .NET Core Runtime 3.1, 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.

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.

   1. Stop the Linux VDA services:

      sudo /sbin/service ctxvda stop  
      
      sudo /sbin/service ctxhdx stop
      <!--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:

      sudo rpm -e XenDesktopVDA
      <!--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. 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.

3. Install the Linux VDA

   • Install the Linux VDA software using Yum:

     For Amazon Linux 2:

      sudo yum install -y XenDesktopVDA-<version>.amzn2.x86_64.rpm
      <!--NeedCopy-->
     

     For CentOS 8 and RHEL 8:

      sudo yum install -y XenDesktopVDA-<version>.el8_x.x86_64.rpm
      <!--NeedCopy-->
     

     For CentOS 7 and RHEL 7:

      sudo yum install -y XenDesktopVDA-<version>.el7_x.x86_64.rpm
      <!--NeedCopy-->
     

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

     For Amazon Linux 2:

      sudo rpm -i XenDesktopVDA-<version>.amzn2.x86_64.rpm
      <!--NeedCopy-->
     

     For CentOS 8 and RHEL 8:

      sudo rpm -i XenDesktopVDA-<version>.el8_x.x86_64.rpm
      <!--NeedCopy-->
     

     For CentOS 7 and RHEL 7:

      sudo rpm -i XenDesktopVDA-<version>.el7_x.x86_64.rpm
      <!--NeedCopy-->
     

     RPM dependency list for CentOS 8 and RHEL 8:

      qt5-qtbase >= 5.5~
     
      ibus >= 1.5
     
      nss-tools >= 3.44.0
     
      gperftools-libs >= 2.4
     
      cyrus-sasl-gssapi >= 2.1
     
      python2 >= 2.7~
     
      postgresql-jdbc >= 42.2.3
     
      postgresql-server >= 10.6
     
      java-11-openjdk >= 11
     
      icoutils >= 0.32
     
      firewalld >= 0.8.0
     
      policycoreutils-python-utils >= 2.9
     
      python3-policycoreutils >= 2.9
     
      dbus >= 1.12.8
     
      dbus-common >= 1.12.8
     
      dbus-daemon >= 1.12.8
     
      dbus-tools >= 1.12.8
     
      dbus-x11 >= 1.12.8
     
      xorg-x11-server-utils >= 7.7
     
      xorg-x11-xinit >= 1.3.4
     
      libXpm >= 3.5.12
     
      libXrandr >= 1.5.1
     
      libXtst >= 1.2.3
     
      motif >= 2.3.4
     
      pam >= 1.3.1
     
      util-linux >= 2.32.1
     
      util-linux-user >= 2.32.1
     
      xorg-x11-utils >= 7.5
     
      bash >= 4.4
     
      findutils >= 4.6
     
      gawk >= 4.2
     
      sed >= 4.5
     
      cups >= 2.2
     
      foomatic-filters >= 4.0.9
     
      cups-filters >= 1.20.0
     
      ghostscript >= 9.25
     
      libxml2 >= 2.9
     
      libmspack >= 0.7
      <!--NeedCopy-->
     

     RPM dependency list for Amazon Linux 2, CentOS 7, and RHEL 7:

      qt5-qtbase >= 5.5~
     
      libmspack >= 0.5
     
      ibus >= 1.5
     
      cyrus-sasl-gssapi >= 2.1
     
      gperftools-libs >= 2.4
     
      nss-tools >= 3.44.0
     
      postgresql-server >= 9.2
     
      postgresql-jdbc >= 9.2
     
      java-11-openjdk >= 11
     
      ImageMagick >= 6.7.8.9
     
      firewalld >= 0.3.9
     
      policycoreutils-python >= 2.0.83
     
      dbus >= 1.6.12
     
      dbus-x11 >= 1.6.12
     
      xorg-x11-server-utils >= 7.7
     
      xorg-x11-xinit >= 1.3.2
     
      xorg-x11-server-Xorg >= 1.20.4
     
      libXpm >= 3.5.10
     
      libXrandr >= 1.4.1
     
      libXtst >= 1.2.2
     
      motif >= 2.3.4
     
      pam >= 1.1.8
     
      util-linux >= 2.23.2
     
      bash >= 4.2
     
      findutils >= 4.5
     
      gawk >= 4.0
     
      sed >= 4.2
     
      cups >= 1.6.0
     
      foomatic-filters >= 4.0.9
     
      openldap >= 2.4
     
      cyrus-sasl >= 2.1
     
      cyrus-sasl-gssapi >= 2.1
     
      libxml2 >= 2.9
     
      python-requests >= 2.6.0
     
      gperftools-libs >= 2.4
     
      rpmlib(FileDigests) <= 4.6.0-1
     
      rpmlib(PayloadFilesHavePrefix) <= 4.0-1
     
      pmlib(CompressedFileNames) <= 3.0.4-1
     
      rpmlib(PayloadIsXz) <= 5.2-1
      <!--NeedCopy-->
     

   Note:

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

   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.

To upgrade an existing installation

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

Note:

Upgrading an existing installation overwrites the configuration files under /etc/xdl. Before you conduct an upgrade, make sure to back up the files.

• To upgrade your software using Yum:

  For Amazon Linux 2:

   sudo yum install -y XenDesktopVDA-<version>.amzn2.x86_64.rpm
   <!--NeedCopy-->
  

  For CentOS 8 and RHEL 8:

   sudo yum install -y XenDesktopVDA-<version>.el8_x.x86_64.rpm
   <!--NeedCopy-->
  

  For CentOS 7 and RHEL 7:

   sudo yum install -y XenDesktopVDA-<version>.el7_x.x86_64.rpm
   <!--NeedCopy-->
  

• To upgrade your software using the RPM package manager:

  For Amazon Linux 2:

   sudo rpm -U XenDesktopVDA-<version>.amzn2.x86_64.rpm
   <!--NeedCopy-->
  

  For CentOS 8 and RHEL 8:

   sudo rpm -U XenDesktopVDA-<version>.el8_x.x86_64.rpm
   <!--NeedCopy-->
  

  For CentOS 7 and RHEL 7:

   sudo rpm -U XenDesktopVDA-<version>.el7_x.x86_64.rpm
   <!--NeedCopy-->
  

Note:

If you are using RHEL 7, make sure to complete the following steps after you run the preceding upgrade commands:

1. run /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent" -t "REG_SZ" -v "DotNetRuntimePath" -d "/opt/rh/rh-dotnet31/root/usr/bin/" --force to set the right .NET runtime path.
2. Restart the ctxvda service.

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 hypervisors, see the following guides:

• Citrix Hypervisor
• VMware ESX
• Nutanix AHV

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.

4. Prepare the VM for the NVIDIA GRID driver:

   yum install gcc
   
   yum install "kernel-devel-$(uname -r)"
   
   systemctl set-default multi-user.target
   <!--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. Before 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. Review Help about the script before proceeding:

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

Prompted configuration

Run a manual configuration with prompted questions:

sudo /opt/Citrix/VDA/sbin/ctxsetup.sh
<!--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 Delivery Controller Fully Qualified Domain Names (FQDNs) to use for registering with a Delivery Controller. 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 machine 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 open the required ports (ports 80 and 1494 by default) automatically 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
• 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 ports. 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 the 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 the 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 3.1 for supporting the new broker agent service (ctxvda). The default path is /usr/bin.

• CTX_XDL_DESKTOP _ENVIRONMENT=gnome/mate – Specifies the GNOME or MATE desktop environment to use in sessions. If you leave the variable unspecified, the desktop currently installed on the VDA is used. However, if the currently installed desktop is MATE, you must set the variable value to mate.

  Note:

  You can also change the desktop environment for a target session user by completing the following steps:

  1. Create a .xsession file under the $HOME/<username> directory on the VDA.

  2. Edit the .xsession file to specify a desktop environment based on distributions.

     For MATE desktop on Amazon Linux 2, CentOS, Debian, and Ubuntu

     MSESSION=”$(type -p mate-session)”
     if [ -n “$MSESSION” ]; then
     exec mate-session
     fi

     For GNOME desktop on Amazon Linux 2 and CentOS

     GSESSION=”$(type -p gnome-session)”
     if [ -n “$GSESSION” ]; then

        export GNOME_SHELL_SESSION_MODE=classic  
        exec gnome-session --session=gnome-classic      fi   **For GNOME desktop on Ubuntu and Debian**
     

     GSESSION=”$(type -p gnome-session)”
     if [ -n “$GSESSION” ]; then

        exec gnome-session      fi  
     

  3. Share the 700 file permission with the target session user.

• 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.
• CTX_XDL_TELEMETRY_SOCKET_PORT – The socket port for listening for Citrix Scout. The default port is 7503.
• CTX_XDL_TELEMETRY_PORT – The port for communicating with Citrix Scout. The default port is 7502.

Set the environment variable and run the configure script:

export CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N

export CTX_XDL_DDC_LIST='list-ddc-fqdns'

export CTX_XDL_VDA_PORT=port-number

export CTX_XDL_REGISTER_SERVICE=Y|N

export CTX_XDL_ADD_FIREWALL_RULES=Y|N

export CTX_XDL_AD_INTEGRATION=1|2|3|4|5

export CTX_XDL_HDX_3D_PRO=Y|N

export CTX_XDL_VDI_MODE=Y|N

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_FAS_LIST='list-fas-servers' | '<none>'

export CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime

export CTX_XDL_DESKTOP_ENVIRONMENT= gnome | mate | '<none>'

export CTX_XDL_TELEMETRY_SOCKET_PORT=port-number

export CTX_XDL_TELEMETRY_PORT=port-number

export CTX_XDL_START_SERVICE=Y|N

sudo -E /opt/Citrix/VDA/sbin/ctxsetup.sh
<!--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:

sudo CTX_XDL_SUPPORT_DDC_AS_CNAME=Y|N \

CTX_XDL_DDC_LIST='list-ddc-fqdns' \

CTX_XDL_VDA_PORT=port-number \

CTX_XDL_REGISTER_SERVICE=Y|N \

CTX_XDL_ADD_FIREWALL_RULES=Y|N \

CTX_XDL_AD_INTEGRATION=1|2|3|4|5 \

CTX_XDL_HDX_3D_PRO=Y|N \

CTX_XDL_VDI_MODE=Y|N \

CTX_XDL_SITE_NAME=dns-name \

CTX_XDL_LDAP_LIST='list-ldap-servers' \

CTX_XDL_SEARCH_BASE=search-base-set \

CTX_XDL_FAS_LIST='list-fas-servers' \

CTX_XDL_DOTNET_RUNTIME_PATH=path-to-install-dotnet-runtime \

CTX_XDL_DESKTOP_ENVIRONMENT=gnome | mate \

CTX_XDL_TELEMETRY_SOCKET_PORT=port-number \

CTX_XDL_TELEMETRY_PORT=port-number \

CTX_XDL_START_SERVICE=Y|N \

/opt/Citrix/VDA/sbin/ctxsetup.sh
<!--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:

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

To remove configuration changes:

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

Important:

This script deletes all configuration data from the database and renders the Linux VDA inoperable.

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

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

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:

sudo /sbin/service ctxhdx start

sudo /sbin/service ctxvda start
<!--NeedCopy-->

Stop the Linux VDA:

To stop the Linux VDA services:

sudo /sbin/service ctxvda stop

sudo /sbin/service ctxhdx stop
<!--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:

sudo /sbin/service ctxvda stop

sudo /sbin/service ctxhdx restart

sudo /sbin/service ctxvda start
<!--NeedCopy-->

Check the status of the Linux VDA:

To check the running status of the Linux VDA services:

sudo /sbin/service ctxvda status

sudo /sbin/service ctxhdx status
<!--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 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 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 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 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 2112.