Product Documentation

Easy install

May 22, 2017

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

6.9

Yes

Yes

Yes

6.8

Yes

Yes

Yes

6.6

Yes

Yes

Yes

CentOS

7.3

Yes

Yes

Yes

6.8

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

  • Hostname - Linux VDA server name
  • IP address of Domain Name Server
  • IP address or string name of NTP Server
  • Domain Name - a short NetBIOS name of the Active Directory domain
  • Realm Name - an identification string used for network routing and authentication.
  • 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

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

For RHEL and CentOS distributions:

command Copy

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

For Ubuntu distributions:

command Copy

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

sudo apt-get install -f

For SUSE distributions:

command Copy

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

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

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

Interactive mode

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

command Copy

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

Silent mode

To use easy install in silent mode, you must 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
  • CTX_EASYINSTALL_REALM=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 using a TCP/IP port. 
  • CTX_XDL_REGISTER_SERVICE=Y | N – The Linux Virtual Desktop services support starting during boot. 
  • 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 (by default ports 80 and 1494) in the system firewall for the Linux Virtual Desktop. 
  • 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 VDA is configured for VDI desktops (single-session) mode - (i.e. CTX_XDL_VDI_MODE=Y). This is not supported on SUSE. Ensure this value is set to N.
  • 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 to Y. 
  • CTX_XDL_SITE_NAME=dns-name – The Linux VDA discovers LDAP servers using DNS, querying for LDAP service records. 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 by default queries DNS to discover LDAP servers. However, if DNS cannot provide LDAP service records, you can provide a space-separated list of LDAP Fully Qualified Domain Names (FQDNs) with LDAP port (e.g. ad1.mycompany.com:389). If unnecessary, it can be set to '<none>'. 
  • CTX_XDL_SEARCH_BASE=search-base – The Linux VDA by default queries LDAP using a search base set to the root of the Active Directory Domain (e.g. DC=mycompany,DC=com). However, to improve search performance, you can specify a search base (e.g. 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 provided that all parameters can be provided by environment variables.

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

command Copy

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=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=seach-base-set  |'<none>'

export CTX_XDL_START_SERVICE=Y | N

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

You must provide the -E option with sudo to pass the existing environment variables to the new shell it creates. Citrix recommends that you create a shell script file from the commands above with #!/bin/bash as the first line.

Alternatively, you can specify all parameters with a single command:

command Copy

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=seach-base-set \

                  CTX_XDL_START_SERVICE=Y \

                  /opt/Citrix/VDA/sbin/ctxinstall.sh

Considerations

1. 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 on the Linux VDA server if it does not exist.
b. Add the line "workgroup=<your workgroup> to the file.

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

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

log Copy

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

         : This machine's subnet is not known by AD.

         : We guess you should be in the site Site1.

This is due to the special configuration of Centrify. Follow the steps below 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.

4. The ctxinstall.sh script needs the Centrify package if you choose Centrify as the method to join a domain. There are two ways for ctxinstall.sh to get the Centrify package:

  • Easy install helps download the Centrify package from the Internet automatically. Currently the given URLs for each distribution are as follows:

RHEL: wget http://edge.centrify.com/products/centrify-suite/2016-update-1/installers/centrify-suite-2016.1-rhel4-x86_64.tgz?_ga=1.178323680.558673738.1478847956

CentOS: wget http://edge.centrify.com/products/centrify-suite/2016-update-1/installers/centrify-suite-2016.1-rhel4-x86_64.tgz?_ga=1.186648044.558673738.1478847956

SUSE: wget http://edge.centrify.com/products/centrify-suite/2016-update-1/installers/centrify-suite-2016.1-suse10-x86_64.tgz?_ga=1.10831088.558673738.1478847956

Ubuntu: wget http://edge.centrify.com/products/centrify-suite/2016-update-1/installers/centrify-suite-2016.1-deb7-x86_64.tgz?_ga=1.178323680.558673738.1478847956

  • Fetch the Centrify package from a local directory: You must follow the steps below to designate the directory of the Centrify package:

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

For example:

command Copy

cat /tmp/ctxinstall.conf

set “centrifypkgpath=/home/mydir”

ls  -ls  /home/mydir

                  9548 -r-xr-xr-x. 1 root root  9776688 May 13  2016 adcheck-rhel4-x86_64

                  4140 -r--r--r--. 1 root root  4236714 Apr 21  2016 centrifyda-3.3.1-rhel4-x86_64.rpm

                  33492 -r--r--r--. 1 root root 34292673 May 13  2016 centrifydc-5.3.1-rhel4-x86_64.rpm

                  4 -rw-rw-r--. 1 root root     1168 Dec  1  2015 centrifydc-install.cfg

                  756 -r--r--r--. 1 root root   770991 May 13  2016 centrifydc-ldapproxy-5.3.1-rhel4-x86_64.rpm

                  268 -r--r--r--. 1 root root   271296 May 13  2016 centrifydc-nis-5.3.1-rhel4-x86_64.rpm

                  1888 -r--r--r--. 1 root root  1930084 Apr 12  2016 centrifydc-openssh-7.2p2-5.3.1-rhel4-x86_64.rpm

                  124 -rw-rw-r--. 1 root root   124543 Apr 19  2016 centrify-suite.cfg

                   0 lrwxrwxrwx. 1 root root       10 Jul  9  2012 install-express.sh -> install.sh

                  332 -r-xr-xr--. 1 root root   338292 Apr 10  2016 install.sh

                 12 -r--r--r--. 1 root root    11166 Apr  9  2015 release-notes-agent-rhel4-x86_64.txt

                 4 -r--r--r--. 1 root root     3732 Aug 24  2015 release-notes-da-rhel4-x86_64.txt

                 4 -r--r--r--. 1 root root     2749 Apr  7  2015 release-notes-nis-rhel4-x86_64.txt

                12 -r--r--r--. 1 root root     9133 Mar 21  2016 release-notes-openssh-rhel4-x86_64.txt

Troubleshooting

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

Failure when joining a domain with SSSD

An error condition might occur when attempting to join a domain, with the output resembling (verify logs for screen printing):

log Copy

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:

log Copy

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.   

/var/log/messages:

log Copy

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. rm -f /etc/krb5.keytab
  2. net ads leave $REALM -U $domain-administrator
  3. Delete the machine catalog and delivery group on the Delivery Controller
  4. Execute /opt/Citrix/VDA/sbin/ctxinstall.sh
  5. Create the machine catalog and delivery group on the Delivery Controller

Ubuntu can launch a session, but is blocked in an empty desktop

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 appears in the same state when you log on with domain administrator credentials.

To resolve this issue:

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

Ubuntu launches a session, but cannot log on due to missing home directory

/var/log/xdl/hdx.log:

log Copy

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.

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, enter pam-auth-update.

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

localized image

Session cannot be launched or is quickly terminated with dbus/message bus error

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

log Copy

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.

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

log Copy

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

Some groups or modules do not take effect until after a reboot. When dbus or message bus error messages appear in the log, Citrix recommends that you reboot the system and then retry.

SELinux prevents SSHD from accessing the home directory

The user can launch a session but cannot log on.

/var/log/ctxinstall.log:

log Copy

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

To resolve this issue:

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

    SELINUX=disabled

2. Reboot