Product Documentation

VDA Configuration Options - Part 1

Sep 13, 2016

While working on the CXD-302 Advanced Troubleshooting course (if you haven't yet, you should go and take it right away), I started looking at data from Citrix Support. Before starting to teach how to troubleshoot problems, it helps to know which are the most common.

I found that VDA registration has been in the top 5 issues reported to Citrix Support, and in CXD-302 we've dedicated one whole module just to troubleshooting of VDA registration.

Why is it such a big issue? The reason is that registration is a very sensitive operation from a security perspective - you're establishing a connection between the master (controller) and slave (VDA). With such a sensitive operation, the expected behavior is to reject the connection if everything is not in perfect shape. You are establishing two separate communication channels - VDA to XenApp/XenDesktop Delivery Controller (XDC) and a separate channel for the Domain Controller to VDA communication. The action uses Kerberos, so time synchronization or domain membership issues are unforgiving. Also, Kerberos uses Service Principal Names (SPN), so you cannot use a load balanced IP address or hostname.

We have published various articles (including, Troubleshooting XenDesktop registration process) and have provided tools (including Citrix Health Assistant that we updated just a few days ago).

We've made it easier to configure the controller and included additional checks during configuration. For example, in XenApp and XenDesktop 7.9 we are automatically testing the connectivity of the controller during VDA installation; in the past this was optional. An error appears if the controller is not reachable and an additional pop-up message appears if you ignore the warning.

localized image

But when I thought about what else we could do to make this easier for our partners and customers, I realized that we never provided you with any guidance about the first step – where and how to configure the controller address. We have been adding more options and features but have not summarized them in one article.

What do you need to know?

When dealing with VDA configuration of the controller, there are three questions you have to answer during the design phase. In this blog post, we will cover the first two questions.

  • Where do you configure the settings (configuration delivery method)?
  • How do you keep those settings up to date (moving VDA between sites, adding\removing controllers)?
  • How do you configure the settings (the configuration values, like IP, hostname, grouping, alias, etc.)? 

Configuration Options

There are many different ways you can configure the controller (XDC) address on a VDA. You may be familiar with Group Policy configuration and manual entry during VDA installation, but there are a few more options available.

Below are five configuration options that are available to you. Next, we are going to provide short explanations each of those options. We sort the options by their priority (auto-update has higher priority than policy - more about this later).

  1. Auto-Update Method
  2. Policy-based Method (LGPO or GPO)
  3. Registry-based Method (Manual, GPP, specified during installation)
  4. AD-based Method (Legacy OU discovery)
  5. MCS-based Method (Personality.ini)

Auto-Update Method

The Auto-Update Method is one of the hidden gems in FMA that went under the radar of most people. It was first introduced in XenApp and XenDesktop 7.6 and is enabled by default, so you're probably already using it even without knowing about it.

Auto-Update is not dealing with the initial configuration, but it's solving the problem of keeping your environment up-to-date when adding or removing controllers. After initial registration, auto-update functionality downloads the list of all available controllers and stores this in a persistent cache - this is done separately for each VM. This feature supports all provisioning methods (including MCS and PVS) with the exception of server-side cache with PVS (which is not a very common scenario).

Whenever a VDA re-registers, for example after restarting, this cache is updated with the latest changes. Below is an example of the format of this cache file - it's not only caching the host names, but also SIDs (it's a ListOfSIDs that is internally more important than a ListOfDDCs, but that’s a story for another time). As a nice side effect, the VDA doesn't have to query SID anymore, so this is also reducing the load on Active Directory.

localized image

You can retrieve the location of this file can by using a WMI call, but it's stored in a location that's readable by the SYSTEM account only and any modification with it is unsupported:

Get-WmiObject -Namespace "Root\Citrix\DesktopInformation" -Class "Citrix_VirtualDesktopInfo" -Property "PersistentDataLocation"

You can control the feature by using a Citrix Policy called "Enable auto update of Controllers" under "Virtual Delivery Agent Settings."

If you read the previous text carefully, you may have noticed something strange. Auto-update is the highest priority of all and overrides all other settings, so what would happen if you need to move the VDA to another site (such as in a disaster recovery scenario)? There is a nice sub-feature in auto-update that takes care of this use case. In the preceding screenshot, you might notice a 'NonAutoListOfDDCs' elements (initial configuration option). Auto-update monitors this location and if there are any changes (such as updating the initial method), it will skip the auto-update and move on to the next method.

Policy-based Method (LGPO\GPO)

The Policy-based Method is probably my favorite method for initial configuration. Centralizing the configuration gives you all the advantages of using Group Policy (pretty much standard across enterprises for configuration) and allows you to override auto-update cache in case it is needed.

localized image

You can use a Group Policy (or local GPO in those rare cases where it is required) and find the policy called "Controllers" (or if security is your top priority, "Controller SIDs"). You can find these settings under "Virtual Delivery Agent Settings."

localized image

These settings are then stored together with other policy settings under HKLM\Software\Policies\Citrix\VirtualDesktopAgent (ListOfDDCs). The reason we recommend using GPO for initial configuration is that it's highest in the hierarchy of all the options, except for auto-update, and configuration for all VDAs can be centralized.

Registry-based method

You can use the Registry-based method if you specify the controller address during the VDA installation. You can find these settings in the registry value ListOfDDCs under registry key HKLM\Software\Citrix\VirtualDesktopAgent. If you cannot locate it (and are running 64-bit Windows), you might also have a look in the registry key HKLM\Software\Wow6432Node\Citrix\VirtualDesktopAgent.

localized image

You can also configure this registry key manually or by using the Group Policy Preferences. In some situations, you might prefer using this method instead of using Group Policy - for example, if you want to have conditional processing of different controllers (such as, use XDC-001 for computer names that being with XDW-001-, etc.)

AD-based method (legacy)

The AD-based method supports backward compatibility. Citrix does not support this method. Citrix recommends switching to another method if you still use this method. To enable this method, you have to use the Set-ADControllerDiscovery.ps1 script (available on every controller) and also configure the 'FarmGuid' registry entry on each VDA to point to the right organizational unit (OU). You can also configure this setting by using Group Policy.

localized image

As mentioned before, this is a legacy method that Citrix does not recommend using. You can find more details here if you're interested.

MCS-based method

If you are planning to use Machine Creation Services (MCS) only, you can also consider leaving it up to the MCS to inject the list of controllers. This feature is working together with auto-update, for example, MCS adds the list of controllers to the Personality.ini file during initial provisioning, but auto-update will make sure to keep this list up to date.

localized image

This list is currently injected during catalog creation time. If your environment is small, you do not need to move VDAs between sites. If you're using MCS and don't want to deal with Group Policy for whatever reason, this might be a good option for you. However, Citrix doesn't recommend using this for large environments.


  • VDA Registration process is super-secure
    • It allows you to override configuration if needed
    • Its high priority makes troubleshooting easier
    • Its high priority makes it hard to override
  • Auto-update feature is enabled by default and is the recommended method to keep your list of controllers up-to-date