Product Documentation

Delivery Controller environment

May 10, 2015

In a deployment, 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 Delivery Controller. After you install the initial Controller and create a Site, you can add additional Controllers. 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 SQL Server database activity. Additional Controllers provide the ability to handle more users and more applications and desktop requests, and can improve overall responsiveness.

How Virtual Delivery Agents (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.

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.

Use auto-update

The Enable auto update of Controllers policy setting is located in the Virtual Delivery Agent category.
  • To enable auto-update, enable the Enable auto update of Controllers policy setting. This setting is enabled by default.
  • To disable auto-update, disable the Enable auto update of Controllers policy setting.

When auto-update is enabled and you install a Virtual Delivery Agent (VDA), the VDA attempts to register with one of the Delivery 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 Delivery Controllers

If you do not use auto-update, you must update the Citrix policy setting or registry values for each Virtual Delivery Agent (VDA) in the site (or the VDA image) 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

Update the FQDN values specified in the Controllers policy setting. This policy setting is located in the Virtual Delivery Agent category.

If you also use ListOfSIDs in your deployment, update the SID values specified in the Controller SIDs policy 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.

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.

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 Delivery Controller, you need the following roles or permissions:
Operation Purpose Server role Database role
Database creation Create suitable empty database dbcreator  
Schema creation Create all service-specific schemas and add first Controller to Site securityadmin * db_owner
Add Controller Add Controller (other than the first) to the Site securityadmin * db_owner
Add Controller (mirror server) Add Controller login to the database server currently in the mirror role of a mirrored database securityadmin *  
Remove Controller Remove Controller from the Site   db_owner
Schema update Apply schema updates or hotfixes   db_owner

* While technically more restrictive, in practice, the securityadmin server role should be treated as equivalent to the sysadmin server role.

When using Desktop Studio to perform these operations, the user account must explicitly be a member of the sysadmin server role.

Before adding, removing, or moving a Controller, if your deployment uses database mirroring, 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 get-configdbconnection PowerShell 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 Virtual Delivery Agents (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.

To add a Controller

You cannot add servers installed with an earlier version of this software to a Site that was created with this version.
  1. On the server you want to add, run the installer and select the Delivery Controller and any other core components you want to install.
  2. In Studio, click Join existing deployment and enter the Site address.

To remove a Controller

Removing a Controller 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.

Note: Make sure that 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.

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; 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. In Studio, select Configuration > Controllers in the left pane, then select the Controller you want to remove.
  2. Click 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.
  3. 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.

To 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), in Studio, select Configuration > Controllers in the left pane, then select the Controller you want to move.
  2. Click 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. 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, click Join existing site, and enter the address of the new site.

Move a Virtual Delivery Agent (VDA) to another Site

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. There are two ways to do this: using the installer or Citrix policies.

Move a VDA using the installer

Important: Specify Delivery Controllers in the installer only when the Controllers policy setting is not used.

Run the installer and add a Delivery Controller, specifying the FQDN (DNS entry) of a Controller in Site 2.

Move a VDA using Citrix policies

Use the Group Policy Editor to move multiple VDAs between Sites.

For example:
  1. Create a policy in Site 1 that specifies 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 Desktops, not VDAs for Windows Servers. 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 in To move a controller. After you remove the Controller from the old Site (step 2), run the PowerShell script: Set-ADControllerDiscover –sync.

This script synchronizes the OU with the current set of Controllers. After joining the existing Site (step 4), run the same script on any Controller in the new Site.

Use SSL on Controllers and change HTTP/HTTPS ports

The XML Service runs on the Delivery Controller and supports the HTTP and HTTPS protocols.

To use SSL

For HTTPS, the XML Service supports Secure Sockets Layer (SSL) features through the use of server certificates but not client certificates. To use HTTPS, you must obtain, install, and register a server certificate on all Controllers, and configure a port with the SSL certificate.

To change the default HTTP or HTTPS ports

By default, the XML Service listens on port 80 for HTTP traffic and port 443 for HTTPS traffic. Although you can use non-default ports on a Controller for HTTP or HTTPS traffic, be aware of the security risks of exposing a Controller to untrusted networks. Instead of changing the defaults, it is preferable to deploy a standalone StoreFront server.

  1. Run the following command on the Controller: BrokerService.exe -WIPORT http port -WISSLPORT https port

    http port is the port number for HTTP traffic and https port is the port number for HTTPS traffic.

  2. If you want the XML Service to ignore HTTP or HTTPS traffic on the default ports, set the following registry values on the Controller and restart the Broker Service. Both values are located in HKLM\Software\Citrix\DesktopServer\.
    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.
    • To ignore HTTP traffic, set XmlServicesEnableNonSsl to 0.
    • To ignore HTTPS traffic, set XmlServicesEnableSsl to 0.