Product Documentation

Install Linux Virtual Delivery Agent for Ubuntu

Feb 26, 2018

You can choose to follow the steps in this article for manual installation or use easy install for automatic installation and configuration. Easy install saves time and labor and is less error-prone than the manual installation. 

Note: Use easy install only for fresh installations. Do not use easy install to update an existing installation.

Step 1: Prepare Ubuntu for VDA installation

Step 1a: Verify the network configuration

Citrix recommends that the network is connected and configured correctly before proceeding.

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

For example:

127.0.0.1  vda01.example.com vda01 localhost

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

Note

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

Tip

Use a–z, A–Z, 0–9, and hyphen (-) characters only. Avoid underscores (_), spaces, and other 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:

Command Copy

hostname

This command returns only the host name of the machine and not its FQDN.

Verify that the FQDN is set correctly:

Command Copy

hostname -f

This command returns the FQDN of the machine.

Step 1e: Disable multicast DNS

The default settings have multicast DNS (mDNS) enabled, which can lead to inconsistent name resolution results.

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

Configuration Copy

hosts: files mdns_minimal [NOTFOUND=return] dns

To:

Configuration Copy

hosts: files dns

Step 1f: Check name resolution and service reachability

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

Command Copy

nslookup domain-controller-fqdn

ping domain-controller-fqdn

nslookup delivery-controller-fqdn

ping delivery-controller-fqdn

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

Step 1g: Configure clock synchronization (chrony)

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.

Install chrony:

Command Copy

apt-get install chrony

As a root user, edit /etc/chrony/chrony.conf and add a server entry for each remote time server:

Configuration Copy

server peer1-fqdn-or-ip-address iburst

server peer2-fqdn-or-ip-address iburst

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

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

Save changes and restart the Chrony daemon:

Command Copy

sudo systemctl restart chrony

Step 1h: Install OpenJDK

The Linux VDA depends on OpenJDK. Typically, the runtime environment is installed as part of the operating system installation. Check whether it has been installed with:

Command Copy

sudo apt-get install -y default-jdk

Step 1i: Install PostgreSQL

The Linux VDA requires PostgreSQL Version 9.x on Ubuntu 16.04:

Command Copy

sudo apt-get install -y postgresql

sudo apt-get install -y libpostgresql-jdbc-java

Step 1j: Install Motif

Command Copy

sudo apt-get install -y libxm4

Step 1k: Install other packages

Command Copy

sudo apt-get install -y libsasl2-2

sudo apt-get install -y libsasl2-modules-gssapi-mit

sudo apt-get install -y libldap-2.4-2

sudo apt-get install -y krb5-user

sudo apt-get install -y cups

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 XenServer

When the XenServer Time Sync feature is enabled, within each paravirtualized Linux VM you experience issues with the NTP and the XenServer, 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 XenServer Tools installed, you can check whether the XenServer Time Sync feature is present and enabled from within the Linux VM:

Command Copy

su -

cat /proc/sys/xen/independent_wallclock

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/indepent_wallclock file is not present, the following steps are not required.

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

Command Copy

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

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

Configuration Copy

xen.independent_wallclock = 1

To verify these changes, reboot the system:

Command Copy

su -

cat /proc/sys/xen/independent_wallclock

This command returns the value 1.

Fix time synchronization on Microsoft Hyper-V

Linux VMs with Hyper-V Linux Integration Services installed can leverage the Hyper-V time synchronization feature to use the host operating system's time. To ensure that the system clock remains accurate, this feature must be enabled alongside NTP services.

From the management operating system:

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

Note

This approach is different from VMware and XenServer, 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 Service
  • Centrify DirectControl
  • SSSD

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:

Command Copy

sudo apt-get install winbind samba libnss-winbind libpam-winbind krb5-config krb5-locales krb5-user

Enable Winbind daemon to start on machine startup

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

Command Copy

sudo systemctl enable winbind

Configure Kerberos

Open /etc/krb5.conf as a root user, and make the following settings:

Configuration Copy

[libdefaults]
default_realm = REALM
dns_lookup_kdc = false

[realms]
REALM = {
admin_server = domain-controller-fqdn
kdc = domain-controller-fqdn
}

[domain_realm]
domain-dns-name = REALM
.domain-dns-name = REALM

The domain-dns-name property in this context is the DNS domain name, such as example.com. The REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM.

Configure Winbind Authentication

Configure Winbind manually because Ubuntu does not have a tool like authconfig in RHEL and yast2 in SUSE.

Open /etc/samba/smb.conf, and make the following settings:

Configuration Copy

[global]
workgroup = WORKGROUP
security = ADS
realm = REALM
encrypt passwords = yes
idmap config *:range = 16777216-33554431
winbind trusted domains only = no
kerberos method = secrets and keytab
winbind refresh tickets = yes
template shell = /bin/bash

WORKGROUP is the first field in REALM, and REALM is the Kerberos realm name in uppercase.

Configure nsswitch

Open /etc/nsswitch.conf, and append winbind to the following lines:

Configuration Copy

passwd: compat winbind
group: compat winbind

Join Windows Domain

Your domain controller must be reachable and you must have an Active Directory user account with permissions to add computers to the domain:

Command Copy

sudo net ads join REALM -U user

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

Restart winbind:

Command Copy

sudo systemctl restart winbind

Configure PAM for Winbind

Run the following command and ensure that the Winbind NT/Active Directory authentication and Create home directory on login options are selected:

Command Copy

sudo pam-auth-update

Tip

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

Verify Domain Membership

The Delivery Controller requires that all VDA machines, whether Windows or Linux, have a computer object in Active Directory.

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

Command Copy

sudo net ads testjoin

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

Command Copy

sudo net ads info

Verify Kerberos Configuration

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

Command Copy

sudo klist -ke

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:

Command Copy

sudo kinit -k MACHINE\$@REALM

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:

Command Copy

sudo klist

Examine the account details of the machine using:

Command Copy

sudo net ads status

Verify user authentication

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

Command Copy

wbinfo --krb5auth=domain\\username%password

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, use a domain user account to log on to the Linux VDA. The domain user account has not been used before.

Command Copy

ssh localhost -l domain\\username

id -u

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

Command Copy

ls /tmp/krb5cc_uid

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

Command Copy

klist

Exit the session:

Command Copy

exit

A similar test can be performed by logging on to the Gnome or KDE console directly.

Tip

If you succeed in user authentication but cannot show your desktop when logging on with a domain account, restart the machine and then try again.

Quest authentication service

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

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

Tip

There are several ways to work around this issue, as described here.

The most convenient way is to disable SELinux. As a root user, edit /etc/selinux/config and change the SELinux setting:

Configuration Copy

SELINUX=disabled

This change requires a machine restart:

Command Copy

reboot

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:

Command Copy

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

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

Configure PAM and NSS

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

Command Copy

sudo /opt/quest/bin/vastool configure pam

sudo /opt/quest/bin/vastool configure nss

Join Windows domain

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

Command Copy

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

The user is any domain user with permissions to join computers to the Active Directory domain. The domain-name is the DNS name of the domain; for example, example.com.

Verify domain membership

The Delivery Controller requires that all VDA machines, whether Windows or Linux, have a computer object in Active Directory. To verify that a Quest-joined Linux machine is on the domain:

Command Copy

sudo /opt/quest/bin/vastool info domain

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 Copy

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, use a domain user account to log on to the Linux VDA. The domain user account has not been used before.

Command Copy

ssh localhost -l domain\\username

id -u

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

Command Copy

ls /tmp/krb5cc_uid

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

Command Copy

/opt/quest/bin/vastool klist

Exit the session:

Command Copy

exit

Centrify DirectControl

Join Windows domain

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

Command Copy

su – 

adjoin -w -V -u user domain-name

The user parameter is any Active Directory domain user with permissions to join computers to the Active Directory domain. The domain-name parameter is the name of the domain to join the Linux machine to.

Verify domain membership

The Delivery Controller requires that all VDA machines, whether Windows or Linux, have a computer object in Active Directory. To verify that a Centrify-joined Linux machine is on the domain:

Command Copy

su –

adinfo

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

Command Copy

adinfo --sysinfo all

adinfo --diag

To test connectivity to the various Active Directory and Kerberos services:

Command Copy

adinfo --test

SSSD

Configure Kerberos

Install kerberos

Command Copy

sudo apt-get install krb5-user

To configure Kerberos, open /etc/krb5.conf as root, and make the following settings:

Setting Copy

[libdefaults]

 default_realm = REALM

 dns_lookup_kdc = false

[realms]

 REALM = {

  admin_server = domain-controller-fqdn

  kdc = domain-controller-fqdn

 }

[domain_realm]

 domain-dns-name = REALM

 .domain-dns-name = REALM

The domain-dns-name property in this context is the DNS domain name, such as example.com. The REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM.

Join the domain

SSSD must be configured to use Active Directory as its identity provider and Kerberos for authentication. However, SSSD does not provide AD client functions for joining the domain and managing the system keytab file. There are a few methods for domain joining:

  • adcli
  • samba
  • realmd

Note

This section only provides information for adcli and samba.

Use adcli to join the domain

Install adcli

Install the required package:

Command Copy

sudo apt-get install adcli

Join the domain with adcli

Remove the old system keytab file and join the domain using:

Command Copy

su -

rm -rf /etc/krb5.keytab

adcli join domain-dns-name -U user -H hostname-fqdn

The user is a domain user with permissions to add machines to the domain. The hostname-fqdn is the host name in FQDN format for the machine.

The -H option is necessary for adcli to generate SPN in the format of host/hostname-fqdn@REALM, which the Linux VDA requires.

Verify system keytab

The capabilities of the adcli tool are limited and do not provide a way to test whether a machine is joined to the domain. The best alternative to ensure that the system keytab file has been created:

Command Copy

sudo klist -ket

Verify that the timestamp for each key matches the time the machine was joined to the domain.

Use samba to join the domain

Install the package

Command Copy

sudo apt-get install samba

Configure samba

Open /etc/samba/smb.conf, and make the following settings:

Configuration Copy

[global]

   workgroup = WORKGROUP

   security = ADS

   realm = REALM

   client signing = yes

   client use spnego = yes

   kerberos method = secrets and keytab

WORKGROUP is the first field in REALM, and REALM is the Kerberos realm name in uppercase.

Join the domain with samba

Your domain controller must be reachable and you must have a Windows account with permissions to add computers to the domain.

Command Copy

sudo net ads join REALM -U user

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

Set up SSSD

Install or update required packages

Install the required SSSD and configuration packages if not already installed:

Command Copy

sudo apt-get install sssd

If the packages are already installed, an update is recommended:

Command Copy

sudo apt-get update sssd

Note

By default, the install process in Ubuntu automatically configures nsswitch.conf and the PAM login module.

Configure SSSD

SSSD configuration changes are required before starting the SSSD daemon. For some versions of SSSD, the /etc/sssd/sssd.conf configuration file is not installed by default and must be manually created. As root, either create or open /etc/sssd/sssd.conf and make the following settings:

Configuration Copy

[sssd]

services = nss, pam

config_file_version = 2

domains = domain-dns-name

 

[domain/domain-dns-name]

id_provider = ad

access_provider = ad

auth_provider = krb5

krb5_realm = REALM

# Set krb5_renewable_lifetime higher if TGT renew lifetime is longer than 14 days

krb5_renewable_lifetime = 14d

# Set krb5_renew_interval to lower value if TGT ticket lifetime is shorter than 2 hours

krb5_renew_interval = 1h

krb5_ccachedir = /tmp

krb5_ccname_template = FILE:%d/krb5cc_%U

# This ldap_id_mapping setting is also the default value

ldap_id_mapping = true

override_homedir = /home/%d/%u

default_shell = /bin/bash

ad_gpo_map_remote_interactive = +ctxhdx

Note

ldap_id_mapping is set to true so that SSSD itself takes care of mapping Windows SIDs to Unix UIDs. Otherwise, the Active Directory must be able to provide POSIX extensions (for more information, see the RHEL site). PAM service ctxhdx is added into ad_gpo_map_remote_interactive. For more information, see SSSD GPO-Based Access Control.

The domain-dns-name property in this context is the DNS domain name, such as example.com. The REALM is the Kerberos realm name in uppercase, such as EXAMPLE.COM. There is no requirement to configure the NetBIOS domain name.

Tip

For information on these configuration settings, see the man pages for sssd.conf and sssd-ad.

The SSSD daemon requires that the configuration file must have owner read permission only:

Command Copy

sudo chmod 0600 /etc/sssd/sssd.conf

Start SSSD daemon

Run the following commands to start the SSSD daemon now and to enable the daemon to start upon machine startup:

Command Copy

sudo systemctl start sssd

sudo systemctl enable sssd

PAM configuration

Run the following command and ensure that the SSS authentication and Create home directory on login options are selected:

Command Copy

sudo pam-auth-update

Verify domain membership

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

Use adcli to verify domain membership

Show the domain information by running the following command:

Command Copy

sudo adcli info domain-dns-name

Use samba to verify domain membership

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

Command Copy

sudo net ads testjoin

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

Command Copy

sudo net ads info

Verify Kerberos configuration

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

Command Copy

sudo klist -ke

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:

Command Copy

sudo kinit -k MACHINE\$@REALM

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.

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

Command Copy

sudo klist

Verify user authentication

SSSD does not provide a command-line tool for testing authentication directly with the daemon, and can only be done via PAM.

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

Command Copy

ssh localhost -l domain\\username

id -u

klist 

exit

Check that the Keberos tickets returned by the klist command are correct for that user and have not expired.

As a root user, check that a corresponding ticket cache file was created for the uid returned by the previous id -u command:

Command Copy

ls /tmp/krb5cc_uid

A similar test can be performed by logging on to KDE or Gnome Display Manager.

Step 4: Install the Linux VDA

Step 4a: Download the Linux VDA package

Go to the Citrix website and download the appropriate Linux VDA package based on your Linux distribution. 

Step 4b: Install the Linux VDA

Install the Linux VDA software using the Debian package manager:

Command Copy

sudo dpkg -i xendesktopvda_7.17.0.420-1.ubuntu16.04_amd64.deb

Debian dependency list for Ubuntu:

Dependencies Copy

postgresql >= 9.5

libpostgresql-jdbc-java >= 9.2

default-jdk >= 2:1.8

imagemagick >= 8:6.8.9.9

ufw >= 0.35

ubuntu-desktop >= 1.361

libxrandr2 >= 2:1.5.0

libxtst6 >= 2:1.2.2

libxm4 >= 2.3.4

util-linux >= 2.27.1

bash >= 4.3

findutils >= 4.6.0

sed >= 4.2.2

cups >= 2.1

libldap-2.4-2 >= 2.4.42

libsasl2-modules-gssapi-mit >= 2.1.~

python-requests >= 2.9.1

libgoogle-perftools4 >= 2.4~

xserver-xorg-core >= 2:1.18

xserver-xorg-core << 2:1.19

x11vnc>=0.9.13

python-websockify >= 0.6.1

Note

For information about the Xorg versions and linux distributions that the Linux VDA supports, see the matrix at Citrix article CTX221802.

Step 4c: 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:

Command Copy

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

Prompted configuration

Run a manual configuration with prompted questions:

Command Copy

sudo /opt/Citrix/VDA/sbin/ctxsetup.sh

Automated configuration

For an automated install, the options required by the setup script can be provided with environment variables. If all required variables are present, the script does not prompt the user for any information, allowing for a scripted installation process.

Supported environment variables include:

  • CTX_XDL_SUPPORT_DDC_AS_CNAME = Y | N – The Linux VDA supports specifying a Delivery Controller name using a DNS CNAME record. Set to N by default.
  • CTX_XDL_DDC_LIST = list-ddc-fqdns – The Linux VDA requires a space-separated list of 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. Set to Y by default.
  • CTX_XDL_ADD_FIREWALL_RULES = Y | N – The Linux Virtual Desktop services require incoming network connections to be allowed through the system firewall. You can automatically open the required ports (ports 80 and 1494 by default) in the system firewall for the Linux Virtual Desktop. Set to Y by default.
  • CTX_XDL_AD_INTEGRATION = 1 | 2 | 3 | 4 – 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 Service
    • 3 – Centrify DirectControl
    • 4 – SSSD
  • CTX_XDL_HDX_3D_PRO = Y | N – Linux Virtual Desktop supports HDX 3D Pro, a set of graphics acceleration technologies designed to optimize the virtualization of rich graphics applications. HDX 3D Pro requires a compatible NVIDIA GRID graphics card to be installed. If HDX 3D Pro is selected, the Virtual Delivery Agent is configured for VDI desktops (single-session) mode – (that is, CTX_XDL_VDI_MODE=Y). 
  • CTX_XDL_VDI_MODE = Y | N – Whether to configure the machine as a dedicated desktop delivery model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set this variable to Y. This variable is set to N by default.
  • CTX_XDL_SITE_NAME = dns-name – The Linux VDA discovers LDAP servers through DNS. To limit the DNS search results to a local site, specify a DNS site name. This variable is set to <none> by default.
  • CTX_XDL_LDAP_LIST = list-ldap-servers – The Linux VDA queries DNS to discover LDAP servers. If DNS cannot provide LDAP service records, you can provide a space-separated list of LDAP FQDNs with LDAP port. For example, ad1.mycompany.com:389. This variable is set to <none> by default.
  • CTX_XDL_SEARCH_BASE = search-base – The Linux VDA queries LDAP through a search base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com). However, to improve search performance, you can specify a search base (for example, OU=VDI,DC=mycompany,DC=com). This variable is set to <none> by default.
  • CTX_XDL_START_SERVICE = Y | N – Whether or not the Linux VDA services are started when the Linux VDA configuration is complete. Set to Y by default.

Set the environment variable and run the configure script:

Command Copy

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

export CTX_XDL_HDX_3D_PRO=Y|N

export CTX_XDL_VDI_MODE=Y|N

export CTX_XDL_SITE_NAME=dns-name

export CTX_XDL_LDAP_LIST=list-ldap-servers

export CTX_XDL_SEARCH_BASE=search-base

export CTX_XDL_START_SERVICE=Y|N

sudo -E /opt/Citrix/VDA/sbin/ctxsetup.sh

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

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

Command Copy

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 \

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 \

CTX_XDL_START_SERVICE=Y|N \

/opt/Citrix/VDA/sbin/ctxsetup.sh

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:

Command Copy

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

To remove configuration changes:

Command Copy

sudo /opt/Citrix/VDA/sbin/ctxcleanup.sh

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.

Uninstall the Linux VDA software

Query Linux VDA installation status

To check whether the Linux VDA is installed and to view the version of the installed package:

Command Copy

dpkg -l xendesktopvda

To view more detailed information:

Command Copy

apt-cache show xendesktopvda

Note

Uninstalling the Linux VDA software deletes the associated PostgreSQL and other configuration data. However, the PostgreSQL package and other dependent packages that were set up before the installation of the Linux VDA are not deleted.

Tip

The information in this section does not cover the removal of dependent packages including PostgreSQL.

Step 5: Run the Linux VDA

Once you have configured the Linux VDA using the ctxsetup.sh script, you use the following commands to control the Linux VDA.

Start the Linux VDA

To start the Linux VDA services:

Command Copy

sudo systemctl start ctxhdx

sudo systemctl start ctxvda

Stop the Linux VDA

To stop the Linux VDA services:

Command Copy

sudo systemctl stop ctxvda

sudo systemctl stop ctxhdx

Restart the Linux VDA

To restart the Linux VDA services:

Command Copy

sudo systemctl stop ctxvda

sudo systemctl restart ctxhdx

sudo systemctl restart ctxvda

Check the Linux VDA status

To check the running state of the Linux VDA services:

Command Copy

sudo systemctl status ctxvda

sudo systemctl status ctxhdx

Step 6: Create the machine catalog in XenApp or XenDesktop

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 Server OS option for a hosted shared desktops delivery model. 
    • The Desktop OS option for a VDI dedicated desktop delivery model.
  • Ensure that machines are set as not power managed.
  • Because MCS is not supported for Linux VDAs, choose PVS or the Another service or technology (existing images) deployment method.
  • 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 XenDesktop single user per machine delivery model.

Tip

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

 

Step 7: Create the delivery group in XenApp or XenDesktop

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:

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

For information about how to create machine catalogs and delivery groups, see XenApp and XenDesktop 7.17.