Citrix Connection Leasing - From Citrix24

As I described this in my previous post in XenDesktop and XenApp 7.x IMA (Independent Management Infrastructure) has been replaced with FMA (Flexcast  Management Infrastructure). For more information see post New features in XenApp and XenDesktop 7.6.  In version 7.6 Citrix introduced as a new feature Connection Leasing to supplement SQL High Availability and in fact provide a similar function as the missing Local Host Cache functionality known from XenApp 6.5.

Connection Leasing definition

It’s important to highlight this point because it’s very important to understand the basic. In Citrix eDocs we can find the following statement:

To ensure that the Site database is always available, Citrix recommends starting with a fault-tolerant SQL Server deployment by following high availability best practices from Microsoft. However, network issues and interruptions may prevent Delivery Controllers from accessing the database, resulting in users not being able to connect to their applications or desktop. The connection leasing feature supplements the SQL Server high availability best practices by enabling users to connect and reconnect to their most recently used applications and desktops, even when the Site database is not available.

Does Connection Leasing replace the Local Host Cache ?

In general we can say: No. On the one hand we know that the primary function of connection leasing is to provide the ability to connect to their resources when Site database is not available. This short definition could be compared to the definition of functionality provided by local host cache. On the other hand we know that connection leasing will allow the connection only to the most recently used resourced and has some more limitations. We know also that due to the IMA construction Local Host Cache provide different set of features which are not available in FMA world. All Connection Leasing limitations will be described later in this article.

To summarize the point – connection leasing is very important feature but due to the limitations is a solution only under some circumstances.

Connection Leasing known limitations

Considering the implementation of connection leasing in your environment make sure you understand the limitations:

• Connection leasing is supported for server-hosted applications and desktops, and static (assigned) desktops;
• Connection leasing is not supported for pooled VDI desktops or for users who have not been assigned a desktop when the database becomes unavailable.
• When the Controller is in leased connection mode:
  • Administrators cannot use Studio, Director, or the PowerShell console.
  • Workspace Control is not available. When a user logs on to Receiver, sessions do not automatically reconnect; the user must relaunch the application.
  • If a new lease is created immediately before the database becomes unavailable, but the lease information has not yet been synchronized across all Controllers, the user might not be able to launch that resource after the database becomes unavailable.
  • Server-hosted application and desktop users may use more sessions than their configured session limits. For example:
    • A session may not roam when a user launches it from one device (connecting externally through NetScaler Gateway) when the Controller is not in leased connection mode and then connects from another device on the LAN when the Controller is in leased connection mode.
    • Session reconnection may fail if an application launches just before the database becomes unavailable; in such cases, a new session and application instance are launched.
  • Static (assigned) desktops are not power-managed. VDAs that are powered off when the Controller enters leased connection mode remain unavailable until the database connection is restored, unless the administrator manually powers them on.
  • If session prelaunch and session linger are enabled, new prelaunch sessions are not started. Prelaunched and lingering sessions will not be ended according to configured thresholds while the database is unavailable.
  • Load management within the Site may be affected. Server-based connections are routed to the most recently used VDA. Load evaluators (and especially, session count rules) may be exceeded.
  • The Controller will not enter leased connection mode if you use SQL Server Management Studio to take the database offline. Instead, use one of the following Transact-SQL statements:
    • ALTER DATABASE <database-name> SET OFFLINE WITH ROLLBACK IMMEDIATE
    • ALTER DATABASE <database-name> SET OFFLINE WITH ROLLBACK AFTER <seconds>

How does Connection Leasing work ?

The simplified connection flow is shown in Figure 1. For detailed explanation for connection flow see the following articles: StoreFront location – in DMZ or Not in DMZ ? or XenDesktop 5 – logon process and communication flow.

Connection steps are the following:

1. User opens the StoreFront website and enters credentials
2. StoreFront forwards the credentials
3. Controler authenticates the user and enumerates available resources in the Site database
4. User / Receiver receives the response and starts session

Figure 1

The simplified connection flow when Site database is unavailable is shown in Figure 2.
Connection steps are the following:

1. User opens the StoreFront website and enters credentials
2. StoreFront forwards the credentials
3. Controler authenticates the user and tries to enumerate available resources in the Site database. Since Site database is unavailable this step fails and controler returns an error.
4. User cannot start session

Figure 2

The simplified connection flow with enabled Connection Leasing is shown in Figure 3.
Connection steps are the following:

1. User is authenticated and Controler 1 enumerates available resources in the Site database
2. Controler 1 logs the available resources in a local XML file and keep this record for 14 days
3. XML file is replicated to Controler 2 as part of the next synchronization cycle

Important Note: Each controller talks directly to the site database to get its copy of the leases, they don’t synchronise between each other. In the scenario when database in unavailable (shown in Figure 4) when one controller has a full set of leases and one didn’t, the second controller would not get a copy of the leases from the first controller, it has to wait until the site database is back to get full set of leases.

Figure 3

The simplified connection flow with enabled Connection Leasing when Site database in unavailable is shown in Figure 4.
Connection steps are the following:

1. User opens StoreFront website and enters credential
2. Controler detects the DB is unavailable and uses local XML file insted to enumerate available resources in the Site database
3. User /Receiver receives response and start session

Figure 4

Where the Connection Leasing settings are stored ?

The connection leases entries are kept in Site database, in table chb_State.Leases, (see figure 7 below) but corresponding connection leasing xml files are stored in the hidden folder:  C:\ProgramData\Citrix\Broker\Cache\Leases\Enumeration.

If you are using GPOs to configure your controllers, the GPO will store the configuration details in each controller registry under:

HKLM\Software\Policies\Citrix\DesktopServer\ConnectionLeasing

You should not change the registry values directly if using group policy to configure the settings.
If you are not using a GPO, the configuration is stored under:

HKLM\Software\Citrix\DesktopServer\ConnectionLeasing

How to configure Connection Leasing parameters

The default values used by Connection Leasing should work well with many environments. If you wish to change the default settings you can either:

• Use Group Policy via GPOs – for more information see: Connection Leasing group policy template
• Manually configure the registry on each controller

Note: Connection Leasing does not populate the registry keys by default, so you will need to create them if you wish to change the default values.If you are not using GPOs, in a multi controller site, you will need to edit the registry on each controller.

The used registry settings for Connection Leasing are listed in Table 1 below:

Search:

Name	Type	Default	Info	Summary
DeletionCheckItemLimitPerCycle	int	100	Minimum=1	Setting that controls the number of items check for possible deletion each deletion check interval, per item category. The number of items checked in a particular cycle is by whole subdirectories, so may exceed this limit by the size of the last subdirectory encountered
EnumerationLeaseKeyMask	int	9		Setting that controls the components of the enumeration lease key. Bit 0 - User Sid Bit 1 - Client Name Bit 2 - Client IP Address Bit 3 - ViaAG flag Bit 4 – AccessTags
LaunchRefCacheExpiryMaxMins	int	3	Minutes	Setting that controls the maximum time the logon tickets are cached in memory before they are discarded.
LeaseExpirationTimeInMins	int	20160	Minutes	Setting that specifies the time in minutes after which the lease will expire once it’s stored in the database. The default value of 20160 minutes corresponds to 14 days. The expired leases are removed every 30 minutes by the site service. Setting an expiration value smaller than 30 minutes would need a change to the site service frequency if the lease needs to be removed earlier. Expired leases will not be used by the controller even if they are still present in the lease cache.
LeaseMarkedDeletedTimeInMins	int	30	Minutes	Setting that specific the maximum time a lease will remain in deleted state before its purged.
MaxItemsPerSyncCycle	int	1000		The maximum number of lease to sync per sync cycle. This helps to throttle and restrict the number of disk writes that would be generated every time the sync runs.
MaxRetryDuringLocalCacheDeletion	int	5		Setting that controls the maximum number of time we will attempt to delete the local cache directory in case of IO exceptions.
MinLeaseLifetimeFractionBeforeRef resh	int	10		Setting that specifies the life time of an unchanged lease before its expiration time is refreshed. The value is specified as a fraction of the LeaseExpirationTimeInMins.
PendingFailureMaxSecs	int	90	Seconds	Setting that specific the maximum time in seconds to wait before entering leasing mode on hitting pending failure state in the DAL layer. Note that there is a default timeout of 30 seconds for SQL server queries, this timeout is in addition to that, so the total time for Connection Leasing to become active will be 120 seconds.
SyncCleanupDelaySecs	int	120	Seconds	Setting that controls the time between stale lease and cached data cleanup cycles.
SyncIntervalSecs	int	10	Seconds	Setting that specifies the intervals in which to check for any leases to sync. A sane value must be larger than SiteDynamicDataRefreshPeriodMs, as site dynamic data refreshed will tell when lease and other data last changed.
SyncLocation	string	%ProgramData%\Citrix\Br oker\Cache		The location on local disk where the leases are to be cached.
SyncStartDelayMins	int	1	Minutes	Setting that controls the time to elapse before the first sync can run after the controller service has been started.
UploadQueueIdleMaxSecs	int	10	Seconds	Setting that controls the max time to wait for the upload queue to be idle. Once the queue idle time pass this limit, even if the queue item threshold is not reached the contents of the lease queue will be upload for sync.
UploadQueueMaxItems	int	100		Setting that controls the max items to queue before lease upload is triggered.

How to verify the status of Connection Leasing ?

Connection leasing is enabled by default but the status can be changed from the PowerShell SDK or the Windows registry. The following PowerShell cmdlets affect connection leasing:

• Get-BrokerSite – displays the XenDesktop site active configuration details
• Set-BrokerSite -ConnectionLeasingEnabled $true|$false – turns on/off connection leasing. Default value = $true
• Get-BrokerServiceAddedCapability – displays  “ConnectionLeasing” for the local Controller.
• Get-BrokerLease – retrieves either all or a filtered set of current leases.
• Remove-BrokerLease – marks either one or a filtered set of leases for deletion.
• Update-BrokerLocalLeaseCache – updates the connection leasing cache on the local Controller.

The example of powershell cmdlet output is shown in Figure 5 and 6

Figure 5

Figure 6

The content of  chb_State.Leases table is shown in Figure 7

Figure 7

The content of connection lease xml file is shown in Figure 8

Figure 8

Questions to be answered

1. Where Connection Leasing default settings are stored ? – In the first 7.6 installation in my LAB the registry key mentioned above is empty.

Update 2014.11.14: Default values are hard coded and do not exist in registry. If registry entry is created, new value will be used to overwrite the default setting. Many thanks to Joe Deller for clarifying this.

1. Where association to server hosting the application is stored ? – Using connection leasing, when database is unavailable user will always be routed to the server used when lease was created.

Update 2014.11.04: in the hidden folder Cache the is a collection folders shown in Figure 9. In the the folder Workers there are a random folders created for each user with xml file. An example of a xml file is presented in Figure 10. XML files located in his folder are used to link configured worker to user lease / user id as it is shown in Figure 11. Information about user id is shown in Figure 6 as Owner ID.

Update 2014.11.12:

By default, leases files are stored in subdirectories in %programdata%\Citrix\Broker\Cache:
Apps – contains information about published applications, one file per published app per delivery group; as such this subdirectory should remain relatively small in terms of size and number of objects.
Desktops – contains an entry per user VDA, in a VDI environment this will be one for every user assigned VDI desktop, or in a RDS worker, one entry per published desktop. A VDI environment will therefore normally require much more disk space than a RDS environment as there is a one to one mapping between users and their assigned desktop, rather than the many users to one RDS host desktop.
Icons – will have one entry per unique published application and one for desktops. Normally desktops share one standard icon, unless otherwise configured. If a published application shares the same base executable as another, only one icon entry will be created. Icons will tend to be larger than lease files as they contain the raw bitmap information on how to draw the icon for the application or desktop, but this should still only be in the hundreds of K for a typical icon.
Leases\Enumeration – contains an entry about the resources available to each user, one per user. The size of the file will depend on the number of resources (applications and desktops) available to the user.
Leases\Launch – contains an entry for each successful user VDA login, one for each desktop that the user is entitled to (and has launched) and one for applications. Only a single application lease file is created no matter how many are available to the user as session sharing will normally direct the user to the same host in normal operations. The user can launch any app published from a delivery group from which they have previously launched an app – even if it’s not the same one. It is possible that the enumeration lease might include details of apps/desktops that are no longer available to the user, for example in a scenario where the controller or desktop that hosts the resources is unavailable, there is no load balancing active during Connection Leasing, only the previously connected host will be used.
Workers – contains one entry per VDA, so as per the Desktops directory, a VDI environment will generally contain more lease files than a RDS one; each assigned desktop has data associated with the user, rather than the many users accessing the same RDS host.

The location of the leases can be changed by modifying a registry key, details of which are found at the end of this ocument.

Figure 9

Figure 10

Figure 11