Product Documentation

VDA registration with Controllers

Jun 13, 2017


Before a VDA can be used, it must register (establish communication) with one or more Controllers on the site. The VDA finds a Controller by checking a list of Controllers called the ListofDDCs. The ListOfDDCs on a VDA contains DNS entries that point that VDA to Controllers on the site. For load balancing, the VDA automatically distributes connections across all Controllers in the list.

Why is VDA registration so important? 

  • From a security perspective, registration is a sensitive operation: you’re establishing a connection between the Delivery Controller and the VDA. For such a sensitive operation, the expected behavior is to reject the connection if everything is not in perfect shape. You are effectively establishing two separate communication channels: VDA to Controller, and Controller to VDA. The connection uses Kerberos, so time synchronization and domain membership issues are unforgiving. Kerberos uses Service Principal Names (SPNs), so you cannot use load balanced IP\hostname.
  • If a VDA does not have accurate and current Controller information as you add and remove Controllers in a site, the VDA might reject session launches that were brokered by an unlisted Controller. Invalid entries can delay the startup of the virtual desktop system software. A VDA won't accept a connection from an unknown and untrusted Controller.

In addition to the ListOfDDCs, the ListOfSIDs (Security IDs) indicates which machines in the ListOfDDCs are trusted. The ListOfSIDs can be used to decrease the load on Active Directory or to avoid possible security threats from a compromised DNS server. For more information, see ListOfSIDs below.

If a ListOfDDCs specifies more than one Controller, the VDA attempts to connect to them in random order. The ListOfDDCs can also contain Controller groups. The VDA attempts to connect to each Controller in a group before moving to other entries in the ListOfDDCs.

XenApp and XenDesktop automatically test the connectivity to configured Controllers during VDA installation. Errors are displayed if a Controller cannot be reached. If you ignore a warning that a Controller cannot be contacted (or when you do not specify Controller addresses during VDA installation), messages remind you.

Methods for configuring Controller addresses

The administrator chooses the configuration method to use when the VDA registers with a Controller for the first time. (This is called the initial registration.) During the initial registration, a persistent cache is created on the VDA. During subsequent registrations, the VDA retrieves the list of Controllers from this local cache, unless a configuration change is detected.

The easiest way to retrieve that list during subsequent registrations is by using the auto-update feature. Auto-update is enabled by default. For more information, see Auto-update.

There are several methods for configuring Controller addresses on a VDA.

  • Policy-based (LGPO or GPO)
  • Registry-based (manual, GPP, specified during VDA installation)
  • Active Directory OU-based (legacy OU discovery)
  • MCS-based (personality.ini)

You specify the initial registration method when you install a VDA. (If you disable auto-update, the method you select during VDA installation will also be used for subsequent registrations.)

The following graphic shows the Delivery Controller page of the VDA installation wizard.

localized image

Policy-based (LGPO\GPO)

Citrix recommends using GPO for initial VDA registration. It has the highest priority. (Auto-update is listed above as the highest priority, but auto-update is used only after the initial registration.) Policy-based registration offers the centralizing advantages of using Group Policy for configuration.

To specify this method, complete both of the following steps:

  • On the Delivery Controller page in the VDA installation wizard, select Do it later (advanced). The wizard reminds you several times to specify Controller addresses, even though you're not specifying them during VDA installation. (Because VDA registration is that important!)
  • Enable or disable policy-based VDA registration through Citrix policy with the Virtual Delivery Agent Settings > Controllers setting. (If security is your top priority, use the Virtual Delivery Agent Settings > Controller SIDs setting.)

This setting is stored under HKLM\Software\Policies\Citrix\VirtualDesktopAgent (ListOfDDCs). 

In the last step of the example in the auto-update section, we moved Controller B to a different Site. Auto-update takes care of updating the caches for VDAs in the Site where Controller B previously resided. The administrator for the Site where Controller B now resides simply creates/updates the policy setting to add the FQDN of Controller B.


To specify this method, complete one of the following steps:

  • On the Delivery Controller page in the VDA installation wizard, select Do it manually. Then, enter the FQDN of an installed Controller and then click Add. If you've installed additional Controllers, add their addresses.
  • For a command-line VDA installation, use the /controllers option and specify the FQDNs of the installed Controllers.

This information is usually stored in registry value ListOfDDCs under registry key HKLM\Software\Citrix\VirtualDesktopAgent or HKLM\Software\Wow6432Node\Citrix\VirtualDesktopAgent.

You can also configure this registry key manually or use Group Policy Preferences (GPP). This method might be preferable to the policy-based method (for example, if you want conditional processing of different Controllers, such as: use XDC-001 for computer names that begin with XDW-001-).

Update the ListOfDDCs registry key, which lists the FQDNs of all the Controllers in the Site. (This key is the equivalent of the Active Directory Site OU.) 

HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\ListOfDDCs (REG_SZ)

If the HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent registry location contains both the ListOfDDCs and FarmGUID keys, ListOfDDCs is used for Controller discovery. FarmGUID is present if a site OU was specified during VDA installation. (This might be used in legacy deployments.)

Optionally, update the ListOfSIDs registry key (for more information, see ListOfSIDs below):

HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\ListOfSIDs (REG_SZ)

Remember: If you also enable policy-based VDA registration through Citrix policy, that configuration overrides settings you specify during VDA installation, because it is a higher-priority method.

Active Directory OU-based (legacy)

This method is supported primarily for backward compatibility and is not recommended. If you’re still using it, Citrix suggests changing to another method. 

To specify this method, complete both of the following steps:

  • On the Delivery Controller page in the VDA installation wizard, select Choose locations from Active Directory. 
  • Use the Set-ADControllerDiscovery.ps1 script (available on every Controller). Also, configure the FarmGuid registry entry on each VDA to point to the right OU. This setting can be configured using Group Policy. 

For more details, see Active Directory OU-based discovery.


If you plan to use only MCS to provision VMs, you can instruct MCS to set up the list of Controllers. This feature works with auto-update: MCS injects the list of Controllers into the Personality.ini file during initial provisioning (when creating the machine catalog). Auto-update keeps the list up-to-date.

This method is not recommended for use in large environments. You can use this method if you:

  • Have a small environment
  • Will not move VDAs between sites
  • Use only MCS to provision VMs
  • Don’t want to use Group Policy

To specify this method:

  • On the Delivery Controller page in the VDA installation wizard, select Let Machine Creation Services do it.


As best practice:

  • Use the Group Policy registration method for initial registration.
  • Use auto-update (enabled by default) to keep your list of Controllers up-to-date.
  • In a multi-zone deployment, use Group Policy for initial configuration (with at least two Controllers). Point VDAs to Controllers local to (in) their zone. Use auto-update to keep them up-to-date. Auto-update automatically optimizes the ListOfDDCs for VDAs in satellite zones.


Auto-update (introduced in XenApp and XenDesktop 7.6) is enabled by default. It is the most efficient method for keeping your VDA registrations up-to-date. Although auto-update is not used for initial registration, the auto-update software downloads and stores the ListOfDDCs in a persistent cache on the VDA when initial registration occurs. This is done for each VDA. (The cache also holds machine policy information, which ensures that policy settings are retained across restarts.)

Auto-update is supported when using MCS or PVS to provision machines, except for PVS server-side cache and for persistent VMs that are manually provisioned.

To specify this method:

  • Enable or disable auto-update through a Citrix policy containing the setting: Virtual Delivery Agent Settings > Enable auto update of Controllers. This setting is enabled by default.

How it works:

  • Each time a VDA re-registers (for example, after a machine restart), the cache is updated. Each Controller also checks the site database every 90 minutes. If a Controller has been added or removed since the last check, or if a policy change occurred that affects VDA registration, the Controller sends an updated list to its registered VDAs and the cache is updated. The VDA accepts connections from all the Controllers in its most recently-cached list.
  • If a VDA receives a list that does not include the Controller it is registered with (in other words, that Controller was removed from the site), the VDA re-registers, choosing among the Controllers in the ListOfDDCs. 

For example:

  • A deployment has three Controllers: A, B, and C. A VDA registers with Controller B (which was specified during VDA installation).
  • Later, two Controllers (D and E) are added to the Site. Within 90 minutes, VDAs receive updated lists and then accept connections from Controllers A, B, C, D, and E. (The load is not spread equally to all Controllers until the VDAs are restarted.)
  • Later still, Controller B is moved to another Site. Within 90 minutes, VDAs in the original Site receive updated lists because there has been a Controller change since the last check. The VDA that originally registered with Controller B (which is no longer on the list) re-registers, choosing among the Controllers in the current list (A, C, D, and E).

In a multi-zone deployment, auto-update in a satellite zone automatically caches all local Controllers first. All Controllers in the primary zone are cached in a backup group. If no local Controllers in the satellite zone are available, registration is attempted with Controllers in the primary zone.

As shown in the following example, the cache file contains hostnames and a list of Security IDs (ListOfSIDs). The VDA does not query SIDs, which reduces the Active Directory load.

localized image

You can retrieve the cache file with a WMI call; however, it is stored in a location that's readable only by the SYSTEM account. Important: This information is provided only for information purposes. DO NOT MODIFY THIS FILE. Any modifications to this file or folder results in an unsupported configuration. 

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

If you need to manually configure the ListOfSIDs for security reasons (as distinct from reducing Active Directory load), you cannot use the auto-update feature. For details, see ListOfSIDs below.

Exception to auto-update priority

Although auto-update usually has the highest priority of all VDA registration methods and overrides settings for other methods, there is an exception. The NonAutoListOfDDCs elements in the cache specify the initial VDA configuration method. Auto-update monitors this information. If the initial registration method changes, the registration process skips auto-update, and uses the next-highest configured priority method. This can be helpful when you move a VDA to another site (for example, during disaster recovery).

Configuration considerations

Controller addresses

Regardless of which method you use to specify Controllers, Citrix recommends using an FQDN address. An IP address is not considered a trusted configuration, because it’s easier to compromise an IP than a DNS record. If you populate the ListOfSIDs manually, you can use an IP in a ListOfDDCs. However, FQDN is still recommended.

Load balancing

As noted earlier, the VDA automatically distributes connections across all Controllers in the ListOfDDCs. Failover and load balancing functionality is built into the Citrix Brokering Protocol (CBP). If you specify multiple Controllers in your configuration, registration automatically fails over between them, if needed. With auto-update, automatic failover occurs automatically for all VDAs.

For security reasons, you cannot use a network load balancer, such as NetScaler. VDA registration uses Kerberos mutual authentication, where the client (VDA) must prove its identity to the service (Controller). However, the Controller must prove its identity to the VDA. This means that the VDA and the Controller are acting as server and client at the same time. As noted at the beginning of this article, there are two communications channels: VDA -> Controller and Controller -> VDA.

A component in this process is called Service Principal Name (SPN), which stored as a property in an Active Directory computer object. When your VDA connects to a Controller, it must specify “who” it wants to communicate with; this address is an SPN. If you use a load-balanced IP, mutual Kerberos authentication correctly recognizes that the IP does not belong to the expected Controller.

For more information, see:

Introduction to Kerberos:

Mutual authentication using Kerberos: 

Auto-update replaces CNAME

The auto-update feature replaces the CNAME (DNS alias) function from XenApp and XenDesktop versions earlier than 7.x. CNAME functionality is disabled, beginning with XenApp and XenDesktop 7. Use auto-update instead of CNAME. (If you must use CNAME, see CTX137960. For DNS aliasing to work consistently, do not use both auto-update and CNAME at the same time.)

Controller groups

In certain scenarios, you might want to process Controllers in groups, with one group being preferred and the other group used for a failover if all Controllers fail. Remember that Controllers are randomly selected from the list, so grouping can help enforce preferential use.

Use parentheses to specify groups of controllers. For example, with four Controllers (two primary and two backup), a grouping might be:

(XDC-001.cdz.lan XDC-002.cdz.lan) (XDC-003.cdz.lan XDC-004.cdz.lan).

In this example, the Controllers in the first group (001 and 002) are processed first. If they both fail, Controllers in the second group (003 and 004) are processed.


The list of Controllers that a VDA can contact for registration is the ListOfDDCs. A VDA must also know which Controllers to trust; VDAs do not automatically trust the Controllers in the ListOfDDCs. The ListOfSIDs (Security IDs) identifies the trusted Controllers. VDAs will attempt to register only with trusted Controllers.

In most environments, the ListOfSIDs is generated automatically from the ListOfDDCs. You can use a CDF trace to read the ListOfSIDs.

Generally, there is no need to manually modify the ListOfSIDs. There are several exceptions. The first two exceptions are no longer valid because newer technologies are available.

  • Separate roles for Controllers: Before zones were introduced in XenApp and XenDesktop 7.7, the ListOfSIDs was manually configured when only a subset of Controllers was used for registration. For example, if you were using XDC-001 and XDC-002 as XML brokers, and XDC-003 and XDC-004 for VDA registration, you specified all Controllers in the ListOfSIDs, and XDC-003 and XDC-004 in the ListOfDDCs. This is not a typical or recommended configuration and should not be used in newer environments. Instead, use zones.
  • Reducing Active Directory load: Before the auto-update feature was introduced in XenApp and XenDesktop 7.6, the ListOfSIDs was used to reduce the load on domain controllers. By pre-populating the ListOfSIDs, the resolution from DNS names to SIDs could be skipped. However, the auto-update feature removes the need for this work, because this persistent cache contains SIDs. Citrix recommends keeping the auto-update feature enabled.
  • Security: In some highly secured environments, the SIDs of trusted Controllers were manually configured to avoid possible security threats from a compromised DNS server. However, if you do this, you must also disable the auto-update feature; otherwise the configuration from persistent cache is used.

So, unless you have a specific reason, do not modify the ListOfSIDs. 

If you must modify the ListOfSIDs, create a registry key named ListOfSIDs (REG_SZ) under HKLM\Software\Citrix\VirtualDesktopAgent. The value is a list of trusted SIDs, separated by spaces if you have more than one.

In the following example, one Controller is used for VDA registration (ListOfDDCs), but two Controllers are used for brokering (List OfSIDs).

localized image

Troubleshoot VDA registration issues

As noted previously, a VDA must be registered with a Delivery Controller to be considered when launching brokered sessions. Unregistered VDAs can result in underutilization of otherwise available resources. There are a variety of reasons a VDA might not be registered, many of which an administrator can troubleshoot. Studio provides troubleshooting information in the catalog creation wizard, and after you create a Delivery Group.

Identifying issues during machine catalog creation:

In the catalog creation wizard, after you add existing machines, the list of computer account names indicates whether each machine is suitable for adding to the catalog. Hover over the icon next to each machine to display an informative message about that machine.

If the message identifies a problematic machine, you can either remove that machine (using the Remove button), or add the machine. For example, if a message indicates that information could not be obtained about a machine (perhaps because it had never registered with a Delivery Controller), you might choose to add the machine anyway.

A catalog's functional level controls which product features are available to machines in the catalog. Using features introduced in new product versions may require a new VDA. Setting a functional level makes all features introduced in that version (and later, if the functional level does not change) available to machines in the catalog. However, machines in that catalog with an earlier VDA version will not be able to register. 

Identifying issues after creating Delivery Groups:

After you create a Delivery Group, Studio displays details about machines associated with that group. The details pane for a Delivery Group indicates the number of machines that should be registered but are not. In other words, there might be one or more machines that are powered on and not in maintenance mode, but are not currently registered with a Controller. When viewing a "not registered, but should be" machine, review the Troubleshoot tab in the details pane for possible causes and recommended corrective actions.

For more information about functional levels, see VDA versions and functional levels section in Create Machine Catalogs.

For more information about VDA registration troubleshooting, see CTX136668.

You can also use the Citrix Health Assistant to troubleshoot VDA registration and session launch. For details, see CTX207624.