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

Create a non-domain-joined Linux VDA using easy install (preview)

April 11, 2024
Contributed by: 
B

This article walks you through using the easy install method to create a non-domain-joined Linux VDA in Citrix DaaS.

Important:

Step 1: Create a machine catalog

Create an empty machine catalog with no machines in it. For example, use the Citrix Remote PowerShell SDK and run the following command to create an empty machine catalog that is named Your-catalog-name and supports single-session OS machines.

New-BrokerCatalog -AllocationType 'Static' -Description 'Your description' -MinimumFunctionalLevel 'L7_20' -Name 'Your-catalog-name' -SessionSupport 'SingleSession' -PersistUserChanges 'OnLocal' -ProvisioningType 'Manual' -MachinesArePhysical $true
<!--NeedCopy-->

Keep a record of the UUID of the created catalog. The UUID is needed when you create an enrollment token later.

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 desktop 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.
  • Do not mix domain-joined and non-domain-joined machines in the same machine catalog.
  • Remote PC Access machine catalogs are supported for domain-joined machines only and are not supported for non-domain-joined machines.

Note:

Early versions of Citrix Studio don’t 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.

Step 2: Create a VDA enrollment token

To create a non-domain-joined VDA using easy install, you need a token file to enroll the VDA with a machine catalog and authenticate the VDA to the Citrix Cloud control plane.

To create an enrollment token, send an HTTP POST message similar to the following to the URL: [DdcServerAddress]/citrix/orchestration/api/techpreview/{customerid}/{siteid}/enrollments.

POST https://[DdcServerAddress]/citrix/orchestration/api/techpreview/[customerid]/[siteid]/enrollments HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: Bearer <bearer-token>

{
  "TokenName": "string",
  "IssuedToUser": "string",
  "ExpirationDate": "2023-10-13T08:00:25.796Z",
  "NotValidBeforeDate": "2023-10-13T08:00:25.796Z",
  "NumMachinesAllowed": number,
  "CatalogId": "string"
}
<!--NeedCopy-->

In the HTTP POST message, set CatalogId to the UUID of the machine catalog you created earlier and set [DdcServerAddress] to one of the following as needed:

  • Commercial https://[customerid].xendesktop.net
  • Japan https://[customerid].apps.citrixworkspacesapi.jp
  • Government https://[customerid].xendesktop.us

Step 3: Install .NET

Before installing the Linux VDA, install .NET based on your Linux distribution:

  • Install .NET Runtime 8.0 on all supported Linux distributions except RHEL 7.9 and Amazon Linux 2.
  • For RHEL 7.9 and Amazon Linux 2, continue to install .NET Runtime 6.0.

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

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

Based on the command output, set the .NET runtime binary path. For example, if the command output is /aa/bb/dotnet, use /aa/bb as the .NET binary path.

Step 4: Download the Linux VDA package

  1. Go to the Citrix Virtual Apps and Desktops download page.
  2. Expand the appropriate version of Citrix Virtual Apps and Desktops.

  3. Expand Components to find the Linux VDA. For example:

    Components for Citrix Virtual Apps and Desktops

  4. Click the Linux VDA link to access the Linux VDA downloads.

    Linux VDA downloads

  5. Download the Linux VDA package that matches your Linux distribution.

  6. Download the GPG public key that you can use to verify the integrity of the Linux VDA package. For example:

    GPG public key

    To verify the integrity of the Linux VDA package by using the public key:

    • For an RPM package, run the following commands to import the public key into the RPM database and to check the package integrity:

       rpmkeys --import <path to the public key>
 rpm --checksig --verbose <path to the Linux VDA package>
 <!--NeedCopy-->

    • For a DEB package, run the following commands to import the public key into the DEB database and to check the package integrity:

       sudo apt-get install dpkg-sig
 gpg --import <path to the public key>
 dpkg-sig --verify <path to the Linux VDA package>
 <!--NeedCopy-->

Step 5: Install the Linux VDA package

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

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

Note:

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

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

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

Note:

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

nmcli dev connect eth0
systemctl restart NetworkManager
<!--NeedCopy-->

For Ubuntu/Debian distributions:

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

Note:

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

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

For SUSE distributions:

  1. For SUSE 15.5 on AWS, Azure, and GCP, ensure that:

    • You are using libstdc++6 version 12 or later.
    • The Default_WM parameter in /etc/sysconfig/windowmanager is set to “gnome”.

  2. Run the following command to install the Linux VDA:

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

Step 6: Install NVIDIA GRID drivers

Enabling HDX 3D Pro requires you to install the NVIDIA GRID drivers on your hypervisor and on the VDA machine.

To install and configure the NVIDIA GRID Virtual GPU Manager (the host driver) on the specific hypervisors, see the following guides:

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

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

Step 7: Specify a database to use

You can specify SQLite or PostgreSQL to use by editing /etc/xdl/db.conf after installing the Linux VDA package.

To do so, edit /etc/xdl/db.conf before running sudo /opt/Citrix/VDA/sbin/ctxinstall.sh or /opt/Citrix/VDA/bin/easyinstall.

Note:

  • We recommend you use SQLite for VDI mode only.
  • For easy install and MCS, you can specify SQLite or PostgreSQL to use without having to install them manually. Unless otherwise specified through /etc/xdl/db.conf, the Linux VDA uses PostgreSQL by default.
  • You can also use /etc/xdl/db.conf to configure the port number for PostgreSQL.

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

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

Note:

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

ctxinstall.sh

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

  • Only root can run this script.

  • Easy install uses /opt/Citrix/VDA/sbin/ctxinstall.conf as its configuration file to set, save, and synchronize the values of all environment variables used. We recommend you read the template (ctxinstall.conf.tmpl) carefully and then customize your own ctxinstall.conf. When you first create the configuration file, use either of the following ways:
    • By coping the /opt/Citrix/VDA/sbin/ctxinstall.conf.tmpl template file and saving it as /opt/Citrix/VDA/sbin/ctxinstall.conf.
    • By running ctxinstall.sh. Each time you run ctxinstall.sh, your input is saved in /opt/Citrix/VDA/sbin/ctxinstall.conf.

  • Easy install supports modular running. Modules include pre-check, installation, domain-configuration, setup, and verification.

  • Debugging details for this script can be found in /var/log/xdl/ctxinstall.log.

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

Note:

  • Following the principle of least privilege, ensure that only the root user can read /opt/Citrix/VDA/sbin/ctxinstall.conf because the domain joining password might be set in the file.
  • Uninstalling the Linux VDA removes files under /opt/Citrix/VDA. We recommend you back up /opt/Citrix/VDA/sbin/ctxinstall.conf before uninstalling the VDA.

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

  • **CTX_XDL_NON_DOMAIN_JOINED=’y|n’** – Whether to join the machine to a domain. The default value is ‘n’. For non-domain-joined scenarios, set it to ‘y’.

  • CTX_XDL_NDJ_ENROLLMENT_TOKEN_FILE=’<path-to-token-file-on-vda-machine>‘ – To create a non-domain-joined VDA using easy install, you need a token file to enroll the VDA in a machine catalog of the Delivery Controller. Save the token in a file with least privilege under a proper path.

  • CTX_XDL_VDI_MODE=’y|n’ – Whether to configure the machine as a dedicated desktop delivery model (VDI) or hosted shared desktop delivery model. For HDX 3D Pro environments, set the value to ‘y’.

  • CTX_XDL_HDX_3D_PRO=’y|n’ – The Linux VDA supports HDX 3D Pro, a set of GPU acceleration technologies designed to optimize the virtualization of rich graphics applications. If HDX 3D Pro is selected, the VDA is configured for VDI desktops (single-session) mode - (that is, CTX_XDL_VDI_MODE=’y’).

  • CTX_XDL_START_SERVICE=’y|n’ – Determines whether the Linux VDA services are started when the configuration is complete.

  • CTX_XDL_REGISTER_SERVICE=’y|n’ – The Linux Virtual Desktop services are started after machine startup.

  • CTX_XDL_ADD_FIREWALL_RULES=’y|n’ – The Linux VDA services require incoming network connections to be allowed through the system firewall. You can open the required ports (by default ports 80 and 1494) automatically in the system firewall for the Linux Virtual Desktop.

  • CTX_XDL_DESKTOP_ENVIRONMENT=gnome/gnome-classic/mate – Specifies the GNOME, GNOME Classic, or MATE desktop environment to use in sessions. If you leave the variable unspecified, the default desktop configured on the VDA is used.

  • CTX_XDL_DOTNET_RUNTIME_PATH=’<path-to-install-dotnet-runtime>‘ – The path to install .NET for supporting the new broker agent service (ctxvda). The default path is ‘/usr/bin’.

  • CTX_XDL_VDA_PORT=’<port-number>‘ – The Linux VDA communicates with Delivery Controllers through a TCP/IP port.

Considerations

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

    1. Create an .xsession or .Xclients file under the $HOME/<username> directory on the VDA. If you are using Amazon Linux 2, create an .Xclients file. If you are using other distributions, create an .xsession file.

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

      • For MATE desktop

         MSESSION="$(type -p mate-session)"  
 if [ -n "$MSESSION" ]; then  
 exec mate-session  
 fi
 <!--NeedCopy-->

      • For GNOME Classic desktop

         GSESSION="$(type -p gnome-session)"  
 if [ -n "$GSESSION" ]; then  
 export GNOME_SHELL_SESSION_MODE=classic  
 exec gnome-session --session=gnome-classic  
 fi  
 <!--NeedCopy-->

      • For GNOME desktop

         GSESSION="$(type -p gnome-session)"  
 if [ -n "$GSESSION" ]; then  
 exec gnome-session  
 fi  
 <!--NeedCopy-->
    3. Share the 700 file permission with the target session user.

    Starting with Version 2209, session users can customize their desktop environments. To enable this feature, you must install switchable desktop environments on the VDA in advance. For more information, see Custom desktop environments by session users.

Interactive mode

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

Silent mode

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

If you set it, the exported value for each variable overwrites the value in /Citrix/VDA/sbin/ctxinstall.conf. All updated values are saved in /Citrix/VDA/sbin/ctxinstall.conf.

export CTX_XDL_NON_DOMAIN_JOINED='y'
export CTX_XDL_NDJ_ENROLLMENT_TOKEN_FILE='<token-file-path>'
export CTX_XDL_VDI_MODE='y|n'
export CTX_XDL_START_SERVICE='y|n'
export CTX_XDL_REGISTER_SERVICE='y|n'
export CTX_XDL_ADD_FIREWALL_RULES='y|n'
export CTX_XDL_HDX_3D_PRO='y|n'
export CTX_XDL_DESKTOP_ENVIRONMENT= gnome | gnome-classic | mate | '<none>'
export CTX_XDL_DOTNET_RUNTIME_PATH='<path-to-install-dotnet-runtime>'
export CTX_XDL_VDA_PORT='<port-number>'
sudo -E /opt/Citrix/VDA/sbin/ctxinstall.sh -S
<!--NeedCopy-->

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

Alternatively, you can specify all variables by using a single command.

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

Step 9: Run XDPing

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

Step 10: Run the Linux VDA

Start the Linux VDA:

To start the Linux VDA services:

sudo systemctl start ctxhdx.service

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

Stop the Linux VDA:

To stop the Linux VDA services:

sudo systemctl stop ctxvda.service

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

Note:

Before you stop the ctxvda and ctxhdx services, run the systemctl stop ctxmonitord command to stop the monitor service daemon. Otherwise, the monitor service daemon restarts the services you stopped.

Restart the Linux VDA:

To restart the Linux VDA services:

sudo systemctl stop ctxvda.service

sudo systemctl restart ctxhdx.service

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

Check the status of the Linux VDA:

To check the running status of the Linux VDA services:

sudo systemctl status ctxvda.service

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

Step 11: Create delivery groups

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

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

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

Important:

Publishing applications is supported with Linux VDA Version 1.4 and later. However, the Linux VDA does not support the delivery of desktops and apps to the same machine.

For information about how to create machine catalogs and delivery groups, see Citrix Virtual Apps and Desktops 7 2311.

Create a non-domain-joined Linux VDA using easy install (preview)
April 11, 2024
Contributed by: 
B
April 11, 2024
Contributed by: 
B

In this article

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