Create domain-joined Linux VDAs with FAS enabled using Machine Creation Services (MCS)

Important:

The following are important changes starting with the 2212 release:

• This AD_INTEGRATION variable in the /etc/xdl/mcs/mcs.conf file or on the easy install GUI does not have a default value any longer. You must set a value as needed. For more information, see the Step 3j: Configure MCS variables section in this article.
• The valid value of the UPDATE_MACHINE_PW entry in /etc/xdl/mcs/mcs.conf is no longer enabled or disabled, but Y or N. For more information, see the Automate machine account password updates section in this article.

Supported distributions

If you are using PBIS for joining MCS-created machines to Windows domains, complete the following tasks:

• On the template machine, configure the PBIS package download path in the /etc/xdl/mcs/mcs.conf file or install the PBIS package directly.

• Before you run /opt/Citrix/VDA/sbin/deploymcs.sh, create an Organizational Unit (OU) that has write and password reset permissions to all its subordinate, MCS-created machines.

• Before you restart MCS-created machines after /opt/Citrix/VDA/sbin/deploymcs.sh finishes running, run klist -li 0x3e4 purge on your Delivery Controller or on your Citrix Cloud Connector based on your deployment.

Supported hypervisors

• AWS
• XenServer (formerly Citrix Hypervisor)
• GCP
• Microsoft Azure
• Nutanix AHV
• VMware vSphere

Unexpected results can occur if you try to prepare a master image on hypervisors other than the supported ones.

Create Linux VDAs with FAS enabled using MCS

This section outlines the procedure for creating Linux VDAs using MCS and enabling FAS while preparing a master image on the template VM. If FAS is not enabled on the template VM, you can enable it on each MCS-created VM later by referring to Enable FAS on an MCS-created VM.

Considerations

• Starting with the 2203 release, you can host the Linux VDA on Microsoft Azure, AWS, and GCP for Citrix Virtual Apps and Desktops as well as Citrix DaaS (formerly Citrix Virtual Apps and Desktops service). To add these public cloud host connections to your Citrix Virtual Apps and Desktops deployment, you need the Citrix Universal Hybrid Multi-Cloud (HMC) license.

• Bare metal servers are not supported for use with MCS to create virtual machines.

(For Nutanix only) Step 1: Install and register the Nutanix AHV plug-in

Obtain the Nutanix AHV plug-in package from Nutanix. Install and register the plug-in in your Citrix Virtual Apps and Desktops environment. For more information, see the Nutanix Acropolis MCS plug-in installation guide, available at the Nutanix Support Portal.

Step 1a: Install and register the Nutanix AHV plug-in for on-premises Delivery Controllers

After you install Citrix Virtual Apps and Desktops, select and install the XD MCS AHV Plugin on your Delivery Controllers.

Step 1b: Install and register the Nutanix AHV plug-in for cloud Delivery Controllers

Select and install the CWA MCS AHV Plugin for Citrix Cloud Connectors. Install the plug-in on all Citrix Cloud Connectors that are registered with the Citrix Cloud tenant. You must register Citrix Cloud Connectors even when they serve a resource location without the AHV.

Step 1c: Complete the following steps after installing the plug-in

• Verify that a Nutanix Acropolis folder has been created in C:\Program Files\Common Files\Citrix\HCLPlugins\CitrixMachineCreation\v1.0.0.0.
• Run the "C:\Program Files\Common Files\Citrix\HCLPlugins\RegisterPlugins.exe" -PluginsRoot "C:\Program Files\Common Files\Citrix\HCLPlugins\CitrixMachineCreation\v1.0.0.0" command.

• Restart the Citrix Host, Citrix Broker, and Citrix Machine Creation Services on your on-premises Delivery Controllers or restart the Citrix RemoteHCLServer Service on Citrix Cloud Connectors.

  Tip:

  We recommend that you stop and then restart the Citrix Host, Citrix Broker, and Machine Creation Services when you install or update the Nutanix AHV plug-in.

Step 2: Create a host connection

This section gives examples on how to create a host connection to Azure, AWS, XenServer (formerly Citrix Hypervisor), GCP, Nutanix AHV, and VMware vSphere.

Note:

For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

For more information, see Create and manage connections and resources in the Citrix Virtual Apps and Desktops documentation and Create and manage connections in the Citrix DaaS documentation.

• Create a host connection to Azure in Citrix Studio

• Create a host connection to AWS in Citrix Studio

• Create a host connection to XenServer in Citrix Studio

• Create a host connection to GCP in Citrix Studio

• Create a host connection to Nutanix in Citrix Studio

• Create a host connection to VMware in Citrix Studio

Create a host connection to Azure in Citrix Studio

1. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

2. In the Add Connection and Resources wizard, select Microsoft Azure as the connection type.

3. Select Microsoft Azure as the connection type.

4. The wizard guides you through the pages. Specific page content depends on the selected connection type. After completing each page, select Next until you reach the Summary page. For more information, see Step 2: Create a host connection in the Create non-domain-joined Linux VDAs using MCS article.

Create a host connection to AWS in Citrix Studio

1. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

2. In the Add Connection and Resources wizard, select Amazon EC2 as the connection type.

   For example, in the on-premises Citrix Studio:

   

3. Type the API key and secret key of your AWS account and type your connection name.

   

   The API key is your access key ID and the Secret key is your secret access key. They are considered as an access key pair. If you lose your secret access key, you can delete the access key and create another one. To create an access key, do the following:

   1. Sign in to the AWS services.
   2. Navigate to the Identity and Access Management (IAM) console. 1 On the left navigation pane, choose Users.
   3. Select the target user and scroll down to select the Security credentials tab.
   4. Scroll down and click Create access key. A new window appears.
   5. Click Download .csv file and save the access key to a secure location.

4. The wizard guides you through the pages. Specific page content depends on the selected connection type. After completing each page, select Next until you reach the Summary page.

Create a host connection to XenServer in Citrix Studio

1. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

2. In the Add Connection and Resources wizard, select XenServer (formerly Citrix Hypervisor) in the Connection type field.

3. Type the connection address (the XenServer URL) and credentials.

4. Enter a connection name.

Create a host connection to GCP in Citrix Studio

Set up your GCP environment according to Google Cloud Platform virtualization environments and then complete the following steps to create a host connection to GCP.

1. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

2. In the Add Connection and Resources wizard, select Google Cloud Platform as the connection type.

   For example, in the web-based Studio console on Citrix Cloud:

   

3. Import the service account key of your GCP account and type your connection name.

4. The wizard guides you through the pages. Specific page content depends on the selected connection type. After completing each page, select Next until you reach the Summary page. For more information, see Step 2: Create a host connection in the Create non-domain-joined Linux VDAs using MCS article.

Create a host connection to Nutanix in Citrix Studio

1. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

2. In the Add Connection and Resources wizard, select Nutanix AHV as the connection type on the Connection page, and then specify the hypervisor address, credentials, and your connection name. On the Network page, select a network for the unit.

   For example, in the on-premises Citrix Studio:

   

Create a host connection to VMware in Citrix Studio

1. Install vCenter Server in the vSphere environment. For more information, see VMware vSphere.

2. For on-premises Delivery Controllers, choose Configuration > Hosting > Add Connection and Resources in the on-premises Citrix Studio to create a host connection. For cloud Delivery Controllers, choose Manage > Hosting > Add Connection and Resources in the web-based Studio console on Citrix Cloud to create a host connection.

3. Choose VMware vSphere as the connection type.

   For example, in the on-premises Citrix Studio:

   

4. Type the connection address (the vCenter Server URL) of your VMware account, your credentials, and your connection name.

   

Step 3: Prepare a master image

(For XenServer only) Step 3a: Install XenServer VM Tools

Install XenServer VM Tools on the template VM for each VM to use the xe CLI or XenCenter. VM performance can be slow unless you install the tools. Without the tools, you can’t do any of the following:

• Cleanly shut down, restart, or suspend a VM.
• View the VM performance data in XenCenter.
• Migrate a running VM (through XenMotion).
• Create snapshots or snapshots with memory (checkpoints), and revert to snapshots.
• Adjust the number of vCPUs on a running Linux VM.

1. Download the XenServer VM Tools for Linux file from the XenServer Downloads page or the Citrix Hypervisor Downloads page based on the hypervisor version in use.

2. Copy the LinuxGuestTools-xxx.tar.gz file to your Linux VM or to a shared drive that the Linux VM can access.

3. Extract the contents of the tar file: tar -xzf LinuxGuestTools-xxx.tar.gz

4. Run the following command to install the xe-guest-utilities package based on your Linux distribution.

   For RHEL/CentOS/Rocky Linux/SUSE:

   sudo rpm -i <extract-directory>/xe-guest-utilities_{package-version}_x86.64.rpm
   <!--NeedCopy-->
   

   For Ubuntu/Debian:

   sudo dpkg -i <extract-directory>/xe-guest-utilities_{package-version}_amd64.deb
   <!--NeedCopy-->
   

5. Check the virtualization state of the template VM on the General tab in XenCenter. If XenServer VM Tools are installed correctly, the virtualization state shows Optimized.

Step 3b: Verify configurations for SUSE 15.5 on AWS, Azure, and GCP

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

Step 3c: Disable RDNS for Ubuntu 20.04 on GCP

On the template VM, add the rdns = false line under [libdefaults] in /etc/krb5.conf.

Step 3d: Install .NET on the template VM

Before installing the Linux VDA package, install .NET on the template VM and notice the following:

• In addition to the .NET Runtime, you must install .ASP.NET Core Runtime on all supported Linux distributions before you install or upgrade the Linux VDA. Version 6 is required for Amazon Linux 2. Version 8 is required for other distributions.

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

Step 3e: Install the Linux VDA package on the template VM

After installing .NET, run the following commands based on your Linux distribution to install the Linux VDA:

For RHEL/CentOS/Rocky Linux:

Note:

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

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

For Ubuntu/Debian:

sudo dpkg –i  <PATH>/<Linux VDA DEB>

apt-get install -f
<!--NeedCopy-->

For SUSE:

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

Step 3f: (For RHEL only) Install the EPEL repository that can offer ntfs-3g

Install the EPEL repository on RHEL 8. For information on how to install EPEL, see the instructions at https://docs.fedoraproject.org/en-US/epel/.

Step 3g: (For SUSE only) Manually install ntfs-3g

On the SUSE platform, no repository provides ntfs-3g. Download the source code, compile, and install ntfs-3g manually:

1. Install the GNU Compiler Collection (GCC) compiler system and the make package:

   sudo zypper install gcc
   sudo zypper install make
   <!--NeedCopy-->
   

2. Download the ntfs-3g package.

3. Decompress the ntfs-3g package:

   sudo tar -xvzf ntfs-3g_ntfsprogs-<package version>.tgz
   <!--NeedCopy-->
   

4. Enter the path to the ntfs-3g package:

   sudo cd ntfs-3g_ntfsprogs-<package version>
   <!--NeedCopy-->
   

5. Install ntfs-3g:

   ./configure
   make
   make install
   <!--NeedCopy-->
   

Step 3h: Join the VM to a Windows domain

Join the VM to a Windows domain. We recommend using the easy install script (ctxinstall.sh) for this process, as it saves time, reduces labor, and is less error-prone compared to manual installation. For more information, see Step 8: Run easy install to configure the environment and VDA to complete the installation. If you prefer manual installation, refer to steps 1 through 3 in the manual installation articles under Install the Linux VDA manually.

Step 3i: Configure FAS on the VM

For the detailed steps, see Configure FAS on the Linux VDA.

Step 3j: Configure MCS variables

There are two ways to configure MCS variables:

• Edit the /etc/xdl/mcs/mcs.conf file.

• Use the easy install GUI. To open the easy install GUI, run the /opt/Citrix/VDA/bin/easyinstall command in the desktop environment of your Linux VDA.

  

  Tip:

  Click Save to save variable settings to a local file under the path you specify. Click Load to load variable settings from a file that you specify.

The following are MCS variables that you can configure for FAS enabled scenarios:

-  `Use_AD_Configuration_Files_Of_Current_VDA`: Determines whether to use the existing AD-related configuration files (/etc/krb5.conf, /etc/sssd.conf, and /etc/samba/smb.conf) of the currently running VDA. Set the value to Y when FAS is enabled.

-  `dns`: Sets the IP address for each DNS server. You can set up to four DNS servers.

-  `NTP_SERVER`: Sets the IP address for your NTP server. Unless otherwise specified, it's the IP address of your domain controller.

-  `WORKGROUP`: Sets the workgroup name to the NetBIOS name (case-sensitive) that you configured in AD. Otherwise, MCS uses the part of the domain name that immediately follows the machine hostname as the workgroup name. For example, if the machine account is **user1.lvda.citrix.com**, MCS uses **lvda** as the workgroup name while **citrix** is the correct choice. Ensure that you set the workgroup name correctly.

-  `AD_INTEGRATION`: Sets SSSD, Winbind, or PBIS. For a matrix of the Linux distributions and domain joining methods that MSC supports, see [Supported distributions](#supported-distributions) in this article.

-  `PBIS_DOWNLOAD_PATH`: Sets the path for downloading the PBIS package. The value takes effect only when you set the `AD_INTEGRATION` variable to PBIS.

-  `UPDATE_MACHINE_PW`: Enables or disables automating machine account password updates. For more information, see [Automate machine account password updates](/en-us/linux-virtual-delivery-agent/current-release/installation-overview/use-mcs-to-create-linux-vms.html#automate-machine-account-password-updates).

-  Linux VDA configuration variables:

    `DOTNET_RUNTIME_PATH`=path-to-install-dotnet-runtime  
    `DESKTOP_ENVIRONMENT`=gnome | mate  
    `SUPPORT_DDC_AS_CNAME`=Y | N  
    `VDA_PORT`=port-number  
    `REGISTER_SERVICE`=Y | N  
    `ADD_FIREWALL_RULES`=Y | N  
    `HDX_3D_PRO`=Y | N  
    `VDI_MODE`=Y | N  
    `SITE_NAME`=dns-site-name | '<none\>'  
    `LDAP_LIST`='list-ldap-servers' | '<none\>'  
    `SEARCH_BASE`=search-base-set | '<none\>'    
    `START_SERVICE`=Y | N  
    `TELEMETRY_SOCKET_PORT`=port-number  
    `TELEMETRY_PORT`=port-number  

Step 3k: Write or update registry values for MCS

Add the following command line to the /etc/xdl/mcs/mcs_local_setting.reg file for setting your FAS server addresses:

sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService" -t "REG_SZ" -v "Addresses" -d "<Your-FAS-Server-List>" --force
<!--NeedCopy-->

Note

To modify settings for MCS, you are allowed to edit files under /etc/xdl/ad_join and /etc/xdl/mcs/, but editing any files under /var/xdl/mcs is prohibited.

Step 3l: Create a master image

1. (For SSSD + RHEL 8.x/9.x or Rocky Linux 8.x/9.x only) Run the update-crypto-policies --set DEFAULT:AD-SUPPORT command and then restart the template VM.

2. If you configure MCS variables by editing /etc/xdl/mcs/mcs.conf, run /opt/Citrix/VDA/sbin/deploymcs.sh. If you configure MCS variables by using the GUI, click Deploy. After you click Deploy on the GUI, the variables you set on the GUI override the variables you set in the /etc/xdl/mcs/mcs.conf file.

3. Create and name a snapshot of your master image based on the public cloud you use.

   • (For XenServer, GCP, and VMware vSphere) Install applications on the template VM and shut down the template VM. Create and name a snapshot of your master image.

   • (For Azure) Install applications on the template VM and shut down the template VM from the Azure portal. Ensure that the power status of the template VM is Stopped (deallocated). Remember the name of the resource group here. You need the name to locate your master image on Azure.

     

   • (For AWS) Install applications on the template VM and shut down the template VM from the AWS EC2 portal. Ensure that the instance state of the template VM is Stopped. Right-click the template VM and select Image > Create Image. Type information and make settings as needed. Click Create Image.

     

   • (For Nutanix) On Nutanix AHV, shut down the template VM. Create and name a snapshot of your master image.

     Note:

     You must prefix Acropolis snapshot names with XD_ for use in Citrix Virtual Apps and Desktops. Use the Acropolis console to rename your snapshots when needed. After you rename a snapshot, restart the Create Catalog wizard to obtain a refreshed list.

(For GCP) Step 3m: Configure Ethernet connection on RHEL 8.x/9.x and Rocky Linux 8.x/9.x

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

Step 4: Create a machine catalog

In Citrix Studio or Web Studio, create a machine catalog and specify the number of VMs to create in the catalog. When creating the machine catalog, choose your master image and consider the following:

• On the Container page that is unique to Nutanix, select the container that you specified for the template VM earlier.

• When you create a catalog containing single-session OS machines, the Desktop Experience page appears and it lets you determine what occurs each time a user logs on.

  

  On the Desktop Experience page, select one of:

  • Users connect to a new (random) desktop each time they log on.
  • Users connect to the same (static) desktop each time they log on.

  If you choose the first option, the changes that users make to the desktop will be discarded (non-persistent).

  If you choose the second option and are using MCS to provision the machines, you can configure how user changes to the desktop are handled:

  • Save user changes to the desktop on the local disk (persistent).
  • Discard user changes and clear the virtual desktop when the user logs off (non-persistent). Select this option if you are using the user personalization layer.

• When updating the master image for an MCS catalog containing persistent machines, any new machines added to the catalog use the updated image. Pre-existing machines continue to use the original master image.

For more information, see machine catalog creation in the Citrix Virtual Apps and Desktops documentation and the Citrix DaaS documentation.

Note:

For Nutanix environments, if your machine catalog creation process on the Delivery Controller takes a significant amount of time, go to Nutanix Prism and power on the machine prefixed with Preparation manually. This approach helps to continue the creation process.

Step 5: Create a delivery group

A delivery group is a collection of machines selected from one or more machine catalogs. It specifies which users can use those machines, and the applications and desktops available to those users.

For more information, see delivery group creation in the Citrix Virtual Apps and Desktops documentation and the Citrix DaaS documentation.

Note:

The VMs you create using MCS might not be able to register with Citrix Cloud Connectors and show as Unregistered. The issue occurs when you host the VMs on Azure and join in the AD domain with Samba Winbind. To work around the issue, complete the following steps:

1. Go to the ADSI Edit console, select an unregistered VM, and edit the msDS-SupportedEncryptionTypes attribute of its machine account.
2. Restart the ctxjproxy and ctxvda services on the VM. If the VM’s status changes to Registered, continue with steps 3 through 5.
3. Open the /var/xdl/mcs/ad_join.sh file on the template VM.

4. Add a line of net ads enctypes set $NEW_HOSTNAME$ <Decimal value of encryption type attribute, for example, 28> -U $NEW_HOSTNAME$ -P password after the following lines inside the /var/xdl/mcs/ad_join.sh file:

   if [ "$AD_INTEGRATION" == "winbind" ]; then
                   join_domain_samba
                   restart_service winbind /usr/bin/systemctl
   <!--NeedCopy-->
   

5. Take a new snapshot and create VMs using the new template.

Automate machine account password updates

Machine account passwords, by default, expire 30 days after the machine catalog is created. To prevent password expiration and to automate machine account password updates, do the following:

1. Add the following entry to /etc/xdl/mcs/mcs.conf before running /opt/Citrix/VDA/sbin/deploymcs.sh.

   UPDATE_MACHINE_PW="Y"

2. After running /opt/Citrix/VDA/sbin/deploymcs.sh, open /etc/cron.d/mcs_update_password_cronjob to set the update time and frequency. The default setting updates machine account passwords weekly at 2:30AM, Sunday.

After each machine account password update, the ticket cache on the Delivery Controller becomes invalid and the following error might appear in /var/log/xdl/jproxy.log:

[ERROR] - AgentKerberosServiceAction.Run: GSSException occurred. Error: Failure unspecified at GSS-API level (Mechanism level: Checksum failed)

To eliminate the error, clear the ticket cache regularly. You can schedule a cache cleanup task on all Delivery Controllers or on the domain controller.

Enable FAS on an MCS-created VM

If FAS is not enabled on the template machine as described earlier, you can enable FAS on each MCS-created VM.

To enable FAS on an MCS-created VM, do the following:

1. Set variables in /etc/xdl/mcs/mcs.conf.

   Note:

   Set all necessary variables in /etc/xdl/mcs/mcs.conf because these variables are called upon VM startup.

   1. Set the value of Use_AD_Configuration_Files_Of_Current_VDA to Y.
   2. Set the other variables as required, such as VDI_MODE.

2. Add the following command line to the /etc/xdl/mcs/mcs_local_setting.reg file for setting your FAS server addresses:

   sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService" -t "REG_SZ" -v "Addresses" -d "<Your-FAS-Server-List>" --force
   <!--NeedCopy-->
   

3. Import the root CA certificate.

   sudo cp root.pem /etc/pki/CA/certs/
   <!--NeedCopy-->
   

4. Run the /opt/Citrix/VDA/sbin/ctxfascfg.sh script.