VDA registration
Introduction
Note:
In an on-premises environment, VDAs register with a Delivery Controller. In a Citrix Cloud service environment, VDAs register with a Cloud Connector. In a hybrid environment, some VDAs register with a Delivery Controller while others register with a Cloud Connector.
Before a VDA can be used, it must register (establish communication) with one or more Controllers or Cloud Connectors on the site. The VDA finds a Controller or Connector by checking a list called the ListofDDCs. The ListOfDDCs on a VDA contains DNS entries that point that VDA to Controllers or Cloud Connectors on the site. For load balancing, the VDA automatically distributes connections across all Controllers or Cloud Connectors 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 Controller or Cloud Connector 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 or Cloud Connector, and Controller or Cloud Connector 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 or Cloud Connector information as you add and remove Controllers (or Cloud Connectors), the VDA might reject session launches that are brokered by an unlisted Controller or Cloud Connector. 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 or Cloud Connector.
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.
If a ListofDDCs specifies more than one Controller or Cloud Connector, the VDA attempts to connect to them in random order. In an on-premises deployment, 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.
Citrix Virtual Apps and Desktops automatically tests the connectivity to configured Controllers or Cloud Connectors during VDA installation. Errors are displayed if a Controller or Cloud Connector cannot be reached. If you ignore a warning that a Controller or Cloud Connector cannot be contacted (or when you do not specify Controller or Cloud Connector addresses during VDA installation), messages remind you.
Methods for configuring Controller or Cloud Connector addresses
The administrator chooses the configuration method to use when the VDA registers for the first time (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 or Cloud Connectors 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 or Cloud Connector addresses on a VDA.
- Policy-based (LGPO or GPO)
- Registry-based (manual, Group Policy Preferences (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 is used for subsequent registrations.)
The following graphic shows the Delivery Controller page of the VDA installation wizard.
Policy-based (LGPO\GPO)
Citrix recommends using GPO for initial VDA registration. It has the highest priority. (Although auto-update is listed as the highest priority, 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. (VDA registration is that important.)
- Enable or disable policy-based VDA registration through Citrix policy with the
Virtual Delivery Agent Settings > Controllerssetting. (If security is your top priority, use theVirtual Delivery Agent Settings > Controller SIDssetting.)
This setting is stored under HKLM\Software\Policies\Citrix\VirtualDesktopAgent (ListOfDDCs).
Registry-based
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 more Controllers, add their addresses.
- For a command-line VDA installation, use the /controllers option and specify the FQDNs of the installed Controllers or Cloud Connectors.
This information is 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 or Cloud Connectors, 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 or Cloud Connectors 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 or Cloud Connector 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:
HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent\ListOfSIDs (REG_SZ)
Remember: If you also enable policy-based VDA registration through Citrix policy, that 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.ps1script (available on every Controller). Also, configure theFarmGuidregistry entry on each VDA to point to the right OU. This setting can be configured using Group Policy.
MCS-based
If you use MCS to provision VMs, MCS sets up the list of Controllers or Cloud Connectors. This feature works with auto-update. When creating the catalog, MCS injects the list of Controllers or Cloud Connectors into the Personality.ini file during initial provisioning. Auto-update keeps the list current.
To specify this method, on the Delivery Controller page in the VDA installation wizard, select Let Machine Creation Services do it.
Review and recommendations
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 or Cloud Connectors). Point VDAs to Controllers or Cloud Connectors local to (in) their zone. Use auto-update to keep them up-to-date. Auto-update automatically optimizes the
ListofDDCsfor VDAs in satellite zones. -
List more than one controller on the
ListOfDDCsregistry key, separated by a space or a comma, to prevent registration issues if a Controller is not available. For example:DDC7x.xd.local DDC7xHA.xd.local 32-bit: HKEY_LOCAL_MACHINE \Software\Citrix\VirtualDesktopAgent\ListOfDDCs HKEY_LOCAL_MACHINE \Software\Citrix\VirtualDesktopAgent\ListOfDDCs (REG_SZ) <!--NeedCopy--> - Ensure all values listed under
ListofDDCsmap to a valid fully qualified domain name to prevent startup registration delays.
Auto-update
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 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 process 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 Citrix Provisioning to provision machines, except for Citrix Provisioning server-side cache. Server-side cache is not a common scenario because there is no persistent storage for auto-update cache.
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 or Cloud Connector also checks the site database every 90 minutes. If a Controller or Cloud Connector has been added or removed since the last check, or if a policy change occurred that affects VDA registration, the Controller or Cloud Connector sends an updated list to its registered VDAs and the cache is updated. The VDA accepts connections from all the Controllers or Cloud Connectors in its most recently cached list.
- If a VDA receives a list that does not include the Controller or Cloud Connector it is registered with (in other words, that Controller or Cloud Connector was removed from the site), the VDA re-registers, choosing among the Controllers or Cloud Connectors in the
ListofDDCs.
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 host names and a list of Security IDs (ListofSIDs). The VDA does not query SIDs, which reduces the Active Directory load.
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.
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 process can be helpful when you move a VDA to another site (for example, during disaster recovery).
Configuration considerations
View a common VDA registration configuration.
View VDA registration steps.
Consider the following when configuring items that can affect VDA registration.
Controller or Cloud Connector addresses
Regardless of which method you use to specify Controllers or Cloud Connectors, 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 or Cloud Connectors in the ListofDDCs. Failover and load balancing functionality is built into the Citrix Brokering Protocol (CBP). If you specify multiple Controllers or Cloud Connectors 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 Citrix ADC. VDA registration uses Kerberos mutual authentication, where the client (VDA) must prove its identity to the service (Controller). However, the Controller or Cloud Connector must prove its identity to the VDA. This means that the VDA and the Controller or Cloud Connector are acting as server and client at the same time. As noted at the beginning of this article, there are two communications channels: VDA to Controller/Cloud Connector and Controller/Cloud Connector to 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 or Cloud Connector, 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 or Cloud Connector.
For more information, see:
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/Cloud Connector groups
In certain scenarios, you might want to process Controllers or Cloud Connectors in groups, with one group being preferred and the other group used for a failover if all Controllers/Cloud Connectors fail. Remember that Controllers or Cloud Connectors are randomly selected from the list, so grouping can help enforce preferential use.
These groups are intended for use within a single site (not multiple sites).
Use parentheses to specify groups of Controllers/Cloud Connectors. For example, with four Controllers (two primary and two backups), 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 both fail, Controllers in the second group (003 and 004) are processed.
For XenDesktop 7.0 or higher, there is an extra step you need to perform to use Registration Groups feature. You need to Prohibit the Enable Auto Update of Controller policy from Studio.
ListOfSIDs
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) identify the trusted Controllers. VDAs 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
ListofSIDswas 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 theListofSIDs, and XDC-003 and XDC-004 in theListofDDCs. This is not a typical or recommended configuration. Do not use it in newer environments. Instead, use zones. -
Reducing Active Directory load: Before the auto-update feature was introduced in XenApp and XenDesktop 7.6, the
ListofSIDswas used to reduce the load on domain controllers. By pre-populating theListofSIDs, the resolution from DNS names to SIDs can 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).
Controller search during VDA registration
When a VDA tries to register, the Broker Agent first performs a DNS lookup in the local domain to ensure that the specified Controller can be reached.
If that initial lookup doesn’t find the Controller, the Broker Agent can start a fallback top-down query in AD. That query searches all domains, and repeats frequently. If the Controller address is invalid (for example, the administrator entered an incorrect FQDN when installing the VDA), that query’s activity can potentially lead to a distributed denial of service (DDoS) condition on the domain controller.
The following registry key controls whether the Broker Agent uses the fallback top-down query when it cannot locate a Controller during the initial search.
HKEY_LOCAL_MACHINE\Software\Citrix\VirtualDesktopAgent
- Name:
DisableDdcWildcardNameLookup - Type:
DWORD - Value:
0(default) or any non-zero value
When set to 0, the fallback search is enabled. If the initial search for the Controller fails, the fallback top-down search is started. This is the default behavior. However, if set to any non-zero value, the fallback search is disabled. If the initial search for the Controller fails, the Broker Agent stops looking.
LDAP binding sequencing during VDA registration using a read-only domain controller
When a VDA registers with a read-only domain controller (RODC), the Broker Agent must select which Light Directory Access Protocol (LDAP) binding or bindings to ignore. To make this selection, the Broker Agent requires a suitable registry key.
If a registry key is not provided, or the registry key field is empty, VDA registration with the RODC takes longer because it is required to go through the original LDAP binding sequence.
To modify the LDAP binding sequence, the registry key ListofIgnoredBindings has been added to HKEY_LOCAL_MACHINE\Software\Policies\Citrix\VirtualDesktopAgent. Use of ListofIgnoredBindings lets you modify the LDAP binding sequence as necessary, and thereby speed up VDA registration with a RODC.
- Name:
ListofIgnoredBindings - Type:
REG_SZ - Values:
DefaultPath,DomainPath,PDCPath
The value is a list of binding path options, each separated by a comma. The registry key will ignore any values that it does not recognize as valid.
Troubleshoot VDA registration issues
As noted previously, a VDA must be registered with a Delivery Controller or Cloud Connector to be considered when launching brokered sessions. Unregistered VDAs can result in underutilization of otherwise available resources. There are various 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 was not obtained about a machine (perhaps because it had never registered), 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 might 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.
More information about troubleshooting VDA registration
-
For more information about functional levels, see VDA versions and functional levels.
-
For more information about VDA registration troubleshooting, see CTX136668.
-
You can also use Citrix Scout health checks to troubleshoot VDA registration and session launch. For details, see About health checks.