Product documentation
Linux Virtual Delivery Agent
Current Release 2402 LTSR 2311 2308 2305 2303 2301 2212 2210 2209 2207 2206 2204 2203 LTSR 1912 LTSR 7.15 LTSR
View PDF

Easy install

June 10, 2022
Contributed by: 
B C

Easy install is officially supported as of Version 7.13 of the Linux VDA. Easy install helps you set up the running environment of the Linux VDA by installing the necessary packages and customizing the configuration files automatically.

Supported distributions

  Winbind SSSD Centrify
RHEL 7.3 Yes Yes Yes
RHEL 6.9 Yes Yes Yes
RHEL 6.6 Yes Yes Yes
CentOS 7.3 Yes Yes Yes
Ubuntu 16.04 Yes Yes Yes
SUSE 12.2 Yes No Yes

Use easy install

To use this feature, do the following:

  1. Prepare configuration information and the Linux machine.
  2. Install the Linux VDA package.
    Go to the Citrix website and download the appropriate Linux VDA package based on your Linux distribution.
  3. Set up the runtime environment to complete the Linux VDA installation.

Step 1: Prepare configuration information and the Linux machine

Collect the following configuration information needed for easy install:

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

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.

Step 2: Install the Linux VDA package

Run the following commands to set up the environment for the Linux VDA.

For RHEL and CentOS distributions:

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

For Ubuntu distributions:

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

For SUSE distributions:

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

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

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

Interactive mode:

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

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

Silent mode:

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

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

The following variables are used by ctxsetup.sh:

  • CTX_XDL_SUPPORT_DDC_AS_CNAME=Y | N – The Linux VDA supports specifying a Delivery Controller name using a DNS CNAME record.
  • CTX_XDL_DDC_LIST=list-ddc-fqdns – The Linux VDA requires a space-separated list of 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_VDA_PORT=port-number – The Linux VDA communicates with Delivery Controllers through a TCP/IP port.
  • 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 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.
  • CTX_XDL_HDX_3D_PRO=Y | N – The Linux VDA supports HDX 3D Pro, a set of GPU acceleration technologies designed to optimize the virtualization of rich graphics applications. If HDX 3D Pro is selected, the VDA is configured for VDI desktops (single-session) mode - (that is, CTX_XDL_VDI_MODE=Y).
  • CTX_XDL_VDI_MODE=Y | N – Whether to configure the machine as a dedicated desktop delivery model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set the value to Y.
  • CTX_XDL_SITE_NAME=dns-name – The Linux VDA discovers LDAP servers through DNS. To limit the DNS search results to a local Site, specify a DNS Site name. If unnecessary, it can be 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 port. For example, ad1.mycompany.com:389. If unnecessary, it can be set to <none>.
  • CTX_XDL_SEARCH_BASE=search-base-set – The Linux VDA queries LDAP through a search base set to the root of the Active Directory Domain (for example, DC=mycompany,DC=com). To improve search performance, you can specify a search base (for example, OU=VDI,DC=mycompany,DC=com). If unnecessary, it can be set to <none>.
  • CTX_XDL_START_SERVICE=Y | N – Whether or not the Linux VDA services are started when the configuration is complete.

If any parameters are not set, the installation rolls back to interactive mode, with a prompt for user input. The ctxinstall.sh script does not prompt for answers when all parameters are already set through the environment variables.

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

export CTX_EASYINSTALL_HOSTNAME=host-name

export CTX_EASYINSTALL_DNS=ip-address-of-dns

export CTX_EASYINSTALL_NTPS=address-of-ntps

export CTX_EASYINSTALL_DOMAIN=domain-name

export CTX_EASYINSTALL_REALM=realm-name

export CTX_EASYINSTALL_FQDN=ad-fqdn-name

export CTX_EASYINSTALL_ADINTEGRATIONWAY=winbind | sssd | centrify

export CTX_EASYINSTALL_USERNAME=domain-user-name

export CTX_EASYINSTALL_PASSWORD=password

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_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_START_SERVICE=Y | N

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

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

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

sudo CTX_EASYINSTALL_HOSTNAME=host-name \

CTX_EASYINSTALL_DNS=ip-address-of-dns \

CTX_EASYINSTALL_NTPS=address-of-ntps \

CTX_EASYINSTALL_DOMAIN=domain-name \

CTX_EASYINSTALL_REALM=realm-name \

......

CTX_XDL_SEARCH_BASE=search-base-set \

CTX_XDL_START_SERVICE=Y \

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

Considerations

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

    a. Create the /tmp/ctxinstall.conf file on the Linux VDA machine.
    b. Add the workgroup=<your workgroup> line to the file.

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

  • For Centrify on CentOS, easy install can fail at adcheck, the Centrify environment check tool, and report the following error:

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

    This issue occurs due to the special configuration of Centrify. Do the following to resolve this issue:

    a. Open Administrative Tools on the Delivery Controller.
    b. Select Active Directory Sites and Services.
    c. Add a correct subnet address for Subnets.

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

Troubleshooting

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

Joining a domain by using SSSD fails

An error might occur when you attempt to join a domain, with the output resembling (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:

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

Ubuntu desktop sessions show a gray screen

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

To resolve this issue:

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

Launching Ubuntu desktop sessions fails due to the 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:

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

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

    Image of Ubuntu cannot launch session

Session cannot 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, Citrix recommends that you restart the system and retry.

SELinux prevents SSHD from accessing the home directory

The user can launch a session but cannot log on.

/var/log/ctxinstall.log:

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:

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

    SELINUX=disabled

  2. Restart the VDA.

Easy install
June 10, 2022
Contributed by: 
B C
June 10, 2022
Contributed by: 
B C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.