Product Documentation

Delivery Controllers

Feb 22, 2017

The Delivery Controller is the server-side component that is responsible for managing user access, plus brokering and optimizing connections. Controllers also provide the Machine Creation Services that create desktop and server images.

A Site must have at least one Controller. After you install the initial Controller, you can add more Controllers when you create a Site, or later. There are two primary benefits from having more than one Controller in a Site.

  • Redundancy — As best practice, a production Site should always have at least two Controllers on different physical servers. If one Controller fails, the others can manage connections and administer the Site.
  • Scalability — As Site activity grows, so does CPU utilization on the Controller and database activity. Additional Controllers provide the ability to handle more users and more applications and desktop requests, and can improve overall responsiveness.

Each Controller communicates directly with the Site database. In a Site with more than one zone, the Controllers in every zone communicate with the Site database in the primary zone.

Tip: Do not change the computer name or the domain membership of a Controller after the Site is configured.

How VDAs discover Controllers

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

In addition to the ListOfDDCs, the ListOfSIDs indicates which machine Security IDs (SIDs) the VDA allows to contact it as a Controller. The ListOfSIDs can be used to decrease the load on Active Directory or to avoid possible security threats from a compromised DNS server.

It is important to ensure that the ListOfDDCs and ListOfSIDs on all VDAs contain current information as Controllers are added and removed in the Site. If the lists are not updated, a VDA might reject session launches that were brokered by an unlisted Controller. Invalid entries can delay the startup of the virtual desktop system software. To keep the lists current, you can:

  • Use the auto-update feature, which automatically updates the ListOfDDCs and ListOfSIDs as Controllers are added or removed. By default, auto-update is enabled.
  • Self-manage – that is, manually update policy or registry settings that identify Controllers.

Information in the ListOfDDCs and ListOfSIDs can come from several places in a deployment. The VDA checks the following locations, in order, stopping at the first place it finds the lists:

  1. A persistent storage location maintained for the auto-update feature. This location contains Controller information when auto-update is enabled and after the VDA successfully registers for the first time after installation. (This storage also holds machine policy information, which ensures that policy settings are retained across restarts.) For its initial registration after installation, or when auto-update is disabled, the VDA checks the following locations.
  2. Policy settings (Controllers, Controller SIDs).
  3. The Controller information under the Virtual Desktop Agent key in the registry. The VDA installer initially populates these values, based on Controller information you specify when installing the VDA.
  4. OU-based Controller discovery. This is a legacy method maintained for backward compatibility.
  5. The Personality.ini file created by Machine Creation Services.

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, which are designated by brackets surrounding two or more Controller entries. The VDA attempts to connect to each Controller in a group before moving to other entries in the ListOfDDCs.

For XenDesktop users who have upgraded from versions earlier than 7.0, the auto-update feature replaces the CNAME function from the earlier version. You can manually re-enable the CNAME function, if desired; however, for DNS aliasing to work consistently, you cannot use both the auto-update feature and the CNAME function. See CTX137960 for information about re-enabling the CNAME functionality.

See the Zones article for information about where VDAs attempt to register in a Site that has more than one zone.

Considerations for choosing auto-update or self-manage

The policy setting that enables/disables auto-update is enabled by default.

The following types of deployments cannot use auto-update, and must self-manage.

  • Deployments that use Controller groups.
  • Deployments that use ListOfSIDs for security reasons. (Deployments that use ListOfSIDs to decrease the Active Directory load can use auto-update.)
  • Deployments that use Provisioning Services without a write-back disk.
  • Deployments that use the Controllers or Controller SIDs policy setting.

Auto-update

The Enable auto update of Controllers policy setting is located in the Virtual Delivery Agent category. To enable auto-update, enable the policy setting; this is the default. To disable auto-update, disable the policy setting.

When auto-update is enabled and you install a VDA, the VDA attempts to register with one of the Controller values you specified when you installed the VDA. The installer writes the Controller information you specify during VDA installation to the ListOfDDCs registry value.

After the VDA registers, the Controller with which it registered sends a list of the current Controller Fully Qualified Domain Names (FQDNs) and Security IDs (SIDs) to the VDA. The VDA writes this list to the auto-update persistent storage. Each Controller also checks the Site Configuration Database every 90 minutes for Controller information – if a Controller has been added or removed since the last check, or if a policy change has occurred, the Controller sends updated lists to its registered VDAs. The VDA will accept connections from all the Controllers in the most recent list it received.

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 list. After a VDA registers or re-registers, it receives an updated list.

For example:

  1. A deployment has three Controllers: A, B, and C. A VDA is installed and registers with Controller B (which was specified during VDA installation).
  2. Two Controllers (D and E) are added to the Site. Within 90 minutes, VDAs receive updated lists and will accept connections from Controllers A, B, C, D, and E. (The load will not be spread equally to all Controllers until the VDAs are restarted.)
  3. Controller B is removed from the Site. Within 90 minutes, VDAs receive updated lists because there has been a Controller change since the last check. The VDA installed in step 1 is registered with Controller B, which is no longer on the list, so that VDA re-registers, choosing among the Controllers in the current list (A, C, D, and E).

Self-manage

If you do not use auto-update, you must update the Citrix policy setting or registry values for each VDA in the Site after you add, move, or remove Delivery Controllers in the Site. Registry changes can also be updated using Group Policy Object.

To self-manage using Citrix policy settings:

  1. Update the FQDN values specified in the Controllers policy setting. This policy setting is located in the Virtual Delivery Agent category.
  2. If you also use ListOfSIDs in your deployment, update the SID values specified in the Controller SIDspolicy setting.

To self-manage using the registry:

Caution: Editing the registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

  1. 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.) Separate multiple values with spaces. Surround Controller groups with brackets.

    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.

  2. Optionally, update the ListOfSIDs registry key:

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

Add, remove, or move Controllers

To add, remove, or move a Controller, you must have the server role and database role permissions listed in the Databases article.

Note: Installing a Controller on a node in an SQL clustering or SQL mirroring installation is not supported.

If your deployment uses database mirroring:

  • Before adding, removing, or moving a Controller, ensure that the principal and mirrored databases are both running. In addition, if you are using scripts with SQL Server Management Studio, enable SQLCMD mode before executing the scripts.
  • To verify mirroring after adding, removing, or moving a Controller, run the PowerShell get-configdbconnection cmdlet to ensure that the Failover Partner has been set in the connection string to the mirror.

After you add, remove, or move a Controller:

  • If auto-update is enabled, the VDAs will receive an updated list of Controllers within 90 minutes.
  • If auto-update is not enabled, ensure that the Controller policy setting or ListOfDDCs registry key are updated for all VDAs. After moving a Controller to another Site, update the policy setting or registry key on both Sites.

Add a Controller

You can add Controllers when you create a Site and later. You cannot add Controllers installed with an earlier version of this software to a Site that was created with this version.

  1. Run the installer on a server containing a supported operating system. Install the Delivery Controller component and any other core components you want. Complete the installation wizard.
  2. If you have not yet created a Site, launch Studio; you are prompted to create a Site.  On the Databases page in the Site creation wizard, click the Select button and then add the address of the server where you installed the additional Controller. Important: If you plan to generate scripts that will initialize the databases, add the Controllers before you generate the scripts.
  3. If you have already created a Site, point Studio to the server where you installed the additional Controller. Click Scale your deployment and enter the Site address.

Remove a Controller

Removing a Controller from a Site does not uninstall the Citrix software or any other component; it removes the Controller from the database so that it can no longer be used to broker connections and perform other tasks. If you remove a Controller, you can later add it back to the same Site or to another Site. A Site requires at least one Controller, so you cannot remove the last one listed in Studio.

When you remove a Controller from a Site, the Controller logon to the database server is not removed. This avoids potentially removing a logon that is used by other products' services on the same machine. The logon must be removed manually if it is no longer required; the securityadmin server role permission is needed to remove the logon.

Important: Do not remove the Controller from Active Directory until after you remove it from the Site.

  1. Make sure the Controller is powered on so that Studio loads in less than one hour. Once Studio loads the Controller you want to remove, power off the Controller when prompted to do so.
  2. Select Configuration > Controllers in the Studio navigation pane and then select the Controller you want to remove.
  3. Select Remove Controller in the Actions pane. If you do not have the correct database roles and permissions, you are offered the option of generating a script that allows your database administrator to remove the Controller for you.
  4. You might need to remove the Controller’s machine account from the database server. Before doing this, check that another service is not using the account.

After using Studio to remove a Controller, traffic to that Controller might linger for a short amount of time to ensure proper completion of current tasks. If you want to force the removal of a Controller in a very short time, Citrix recommends you shut down the server where it was installed, or remove that server from Active Directory. Then, restart the other Controllers on the Site to ensure no further communication with the removed Controller.

Move a Controller to another zone

If your Site contains more than one zone, you can move a Controller to a different zone. See the Zones article for information about how this can affect VDA registration and other operations.

  1. Select Configuration > Controllers in the Studio navigation pane and then select the Controller you want to move.
  2. Select Move in the Actions pane.
  3. Specify the zone where you want to move the Controller.

Move a Controller to another Site

You cannot move a Controller to a Site that was created with an earlier version of this software.

  1. On the Site where the Controller is currently located (the old Site), select Configuration > Controllers in the Studio navigation pane and then select the Controller you want to move.
  2. Select Remove Controller in the Actions pane. If you do not have the correct database roles and permissions, you are offered the option of generating a script that allows someone with those permissions (such as a database administrator) to remove the Controller for you. A Site requires at least one Controller, so you cannot remove the last one listed in Studio.
  3. On the Controller you are moving, open Studio, reset the services when prompted, select Join existing site, and enter the address of the new Site.

Move a VDA to another Site

If a VDA was provisioned using Provisioning Services or is an existing image, you can move a VDA to another Site (from Site 1 to Site 2) when upgrading, or when moving a VDA image that was created in a test Site to a production Site. VDAs provisioned using Machine Creation Services (MCS) cannot be moved from one Site to another because MCS does not support changing the ListOfDDCs a VDA checks to register with a Controller; VDAs provisioned using MCS always check the ListOfDDCs associated with the Site in which they were created.

There are two ways to move a VDA to another Site: using the installer or Citrix policies.

Installer: Run the installer and add a Controller, specifying the FQDN (DNS entry) of a Controller in Site 2. Important: Specify Controllers in the installer only when the Controllers policy setting is not used.

Group Policy Editor: The following example moves multiple VDAs between Sites.

  1. Create a policy in Site 1 that contains the following settings, then filter the policy to the Delivery Group level to initiate a staged VDA migration between the Sites.
    Controllers - containing FQDNs (DNS entries) of one or more Controllers in Site 2.
    Enable auto update of Controllers - set to disabled.
  2. Each VDA in the Delivery Group is alerted within 90 minutes of the new policy. The VDA ignores the list of Controllers it receives (because auto-update is disabled); it selects one of the Controllers specified in the policy, which lists the Controllers in Site 2.
  3. When the VDA successfully registers with a Controller in Site 2, it receives the Site 2 ListOfDDCs and policy information, which has auto-update enabled by default. Since the Controller with which the VDA was registered in Site 1 is not on the list sent by the Controller in Site 2, the VDA re-registers, choosing among the Controllers in the Site 2 list. From then on, the VDA is automatically updated with information from Site 2.

Active Directory OU-based Controller discovery

This Delivery Controller discovery method is supported primarily for backward compatibility, and is valid only for Virtual Delivery Agents (VDAs) for Windows Desktop OS, not VDAs for Windows Server OS. Active Directory-based discovery requires that all computers in a Site are members of a domain, with mutual trusting relationships between the domain used by the Controller and the domain(s) used by desktops. If you use this method, you must configure the GUID of the OU in each desktop registry.

To perform an OU-based Controller discovery, run the Set-ADControllerDiscovery.ps1 PowerShell script on the Controller (each Controller contains this script in the folder $Env:ProgramFiles\Citrix\Broker\Service\Setup Scripts). To run the script, you must have CreateChild permissions on a parent OU, plus full administration rights.

When you create a Site, a corresponding Organizational Unit (OU) must be created in Active Directory if you want desktops to discover the Controllers in the Site through Active Directory. The OU can be created in any domain in the forest that contains your computers. As best practice, the OU should also contain the Controllers in the Site, but this is not enforced or required. A domain administrator with appropriate privileges can create the OU as an empty container, then delegate administrative authority over the OU to a Citrix administrator.

The script creates several essential objects. Only standard Active Directory objects are created and used. It is not necessary to extend the schema.

  • A Controllers security group. The computer account of all Controllers in the Site must be a member of this security group. Desktops in a Site accept data from Controllers only if they are members of this security group.

    Ensure that all Controllers have the 'Access this computer from the network' privilege on all virtual desktops running the VDA. You can do this by giving the Controllers security group this privilege. If Controllers do not have this privilege, VDAs will not register.

  • A Service Connection Point (SCP) object that contains information about the Site, such as the Site name. If you use the Active Directory Users and Computers administrative tool to inspect a Site OU, you might need to enable Advanced Features in the View menu to see SCP objects.
  • A container called RegistrationServices, which is created in the Site OU. This contains one SCP object for each Controller in the Site. Each time the Controller starts, it validates the contents of its SCP and updates it, if necessary.

If multiple administrators are likely to add and remove Controllers after the initial installation, they need permissions to create and delete children on the RegistrationServices container, and Write properties on the Controllers security group; these permissions are granted automatically to the administrator who runs the Set-ADControllerDiscovery.ps1 script. The domain administrator or the original installing administrator can grant these permissions, and Citrix recommends setting up a security group to do this.

When you are using a Site OU:

  • Information is written to Active Directory only when installing or uninstalling this software, or when a Controller starts and needs to update the information in its SCP (for example, because the Controller was renamed or because the communication port was changed). By default, the Set-ADControllerDiscovery.ps1 script sets up permissions on the objects in the Site OU appropriately, giving each Controller Write access to its SCP. The contents of the objects in the Site OU are used to establish trust between desktops and Controllers. Ensure that:
    • Only authorized administrators can add or remove computers from the Controllers security group, using the security group's access control list (ACL).
    • Only authorized administrators and the respective Controller can change the information in the controller's SCP.
  • If your deployment uses replication, be aware of potential delays; see the Microsoft documentation for details. This is particularly important if you create the Site OU in a domain that has domain controllers in multiple Active Directory sites. Depending on the location of desktops, Controllers, and domain controllers, changes that are made to Active Directory when you are initially creating the Site OU, installing or uninstalling Controllers, or changing Controller names or communication ports might not be visible to desktops until that information is replicated to the appropriate domain controller. The symptoms of such replication delay include desktops that cannot establish contact with Controllers and are therefore not available for user connections.
  • This software uses several standard computer object attributes in Active Directory to manage desktops. Depending on your deployment, the machine object's fully qualified domain name, as stored in the desktop's Active Directory record, can be included as part of the connection settings that are returned to the user to make a connection. Ensure that this information is consistent with information in your DNS environment.

To move a Controller to another Site using OU-based Controller discovery, follow the directions above for moving a Controller. After you remove the Controller from the old Site (step 2), run the PowerShell script Set-ADControllerDiscovery –sync. This script synchronizes the OU with the current set of Controllers. After joining the existing Site (step 3), run the same script on any Controller in the new Site.

Permissions required for OU-based discovery

To create a Site, the Citrix administrator who runs the script must have rights over the Site OU to create objects (SCP, container, and security group). 

(If the Site OU is not present, the administrator must have rights to create that as well. Citrix recommends that the AD domain administrator pre-create that OU and delegate rights to it to the Citrix Site administrator identity. Optionally, the script can also create the Site OU. To allow this, the administrator needs the “create OU” right on the new OU’s parent OU. However, as noted, Citrix does not recommend this.)

Later, to add or remove a Controller from the Site, the Citrix administrator must have rights to add/remove a machine from the security group, and create/delete an SCP.

During normal operations, Controllers and VDAs need read rights to all objects in the OU and below. VDAs access the OU as their own machine identity; that machine identity needs at least read rights in the OU to be able to discover Controllers. A Controller also needs the rights to set properties on its own SCP object in the container. 

Granting the Citrix administrator full rights to the child OUs will permit all these actions. However, if your deployment has stricter security requirements (such as restricting who can use the script for which action), you can use the Delegation of Control wizard to set specific rights. The following example procedure grants rights to create the Site.

  1. Create an OU to contain the child objects (Service Connection Point (SCP), container, and security group).
  2. Select the OU, then right-click and select Delegate Control.
  3. In the Delegation of Control wizard, specify the domain user to delegate control to for the OU.
  4. On the Tasks to Delegate page, select Create a custom task to delegate.
  5. On the Active Directory Object type page, accept the default This folder, existing objects in this folder, and creation of new objects in this folder.
  6. On the Permissions page, select the Write and Create All Child Objects check boxes.
  7. Finish the wizard to confirm the privileges.