Citrix Connection Leasing

Citrix makes use of SQL Server AlwaysOn, mirroring or clustering abilities within SQL and clustering at the Hypervisor level to ensure that Delivery Controllers have a constant connection to the SQL site database. Citrix Connection Leasing in XenApp/XenDesktop 7.6+ pushes the availability further ensuring that if in the event the database is innaccessible, users most recent connections to desktops and applications are cached on Delivery Controllers and connections can continue to be brokered.

Note: Connection Leasing has been deprecated in XenApp and XenDesktop 7.12. The feature is not removed, and will still be supported up until the next Current Release after the next LTSR release post 7.12.

List of supported SQL Server versions for XenApp and XenDesktop

You may have been familiar with Local Host Cache using IMA versions of Citrix, and it has returned in XenDesktop 7.12.

For FMA versions prior to 7.12 Connection Leasing is the best alternative although it comes with some limitations such as VDA’s becoming unregistered when Connection Leasing is activated which is normal. With Connection Leasing enabled (by default it is) and SQL servers available, two weeks worth of connection leases for users are cached on the Delivery Controllers local disk so that when users connect back to a recently used resource the cache is replayed and allows them to connect to sessions as if the SQL server connection was alive. Keep in mind that if a user has access to an application or desktop but has not made a connection in more than two weeks they won’t be able to connect in this scenario.

When a SQL server connection is lost the Delivery Controllers enter a Leased Connection Mode and use the locally cached information and leases stored in C:\ProgramData\Citrix\Broker\Cache. The cache information is gathered from SQL server with Delivery Controllers checking the site database every 10 seconds to see if changed or updated lease files are available. Up to 1000 lease files are synchronised every 10 seconds. The local cached directory on each Delivery Controller contains the following folders:

  • Apps – Holds information about published applications. One file per application for each Delivery Group.
  • Desktops – Holds a file per VDA. For XenApp Session Hosts this is one file per host, for VDI desktops there is one file per desktop.
  • Icons – One icon file per unique published application and one for desktops. Applications with the same base executable share an icon. Desktops usually share an icon.
  • Leases\Enumeration – Holds information about the resources available to each user, one file per user. These files are used to determine which resources a user has access to.
  • Leases\Launch – Holds an entry for each successful user VDA login. One for each desktop that the user has connected too and one for applications. A single application file is created regardless of how many are available to the user. This means a user can launch any application from a Delivery Group which they have previously launched an application from. This is a bonus as it means more potential access for users.
  • Workers – One file per VDA, quite like the Desktops folder where one file exists per VDI desktop and one per Session Host serving many users. These files are used to send users to the correct VDA.1-min

Lease and cached information is stored for each user the first time they log on and launch a resource from StoreFront. The Delivery Controller checks for new leases every 10 seconds and if new leases are discovered a sync of data is performed and kept for 2 weeks before a new lease is generated. Connection Leasing is only there to soften the blow of a SQL outage, ensuring that the majority of users can connect to their recently used resources whilst the SQL server connection is restoring.

Connection Leasing is supported on server hosted applications and desktops and VDI persistent (statically assigned) desktops. It is not supported for pooled VDI desktops or for when users do not have a static assignment to a desktop. For connection leasing to work VDA’s must be on version 7.6 minumum and Machine Catalogs must be set to VDA 7.6 or later.

If you want to check the state of Connection Leasing on your site run command Get-BrokerSite | select ConnectionLeasingEnabled – here you should see a value of True since Connection Leasing is enabled by default.2-min

To check the cached connections on a Delivery Controller run the Get-BrokerLease command on a Delivery Controller.   As you can see here, when a user logs on the enumeration cache XML file is generated. This file states what resources the user has access to.3-min This file is stored by default on each Delivery Controller under C:\ProgramData\Citrix\Cache\Leases\Enumeration.7-min

When a user launches a resource, a launch XML file is cached.9-minThe file itself is by default stored on all Delivery Controllers within C:\ProgramData\Citrix\Cache\Leases\Enumeration.8-min

To remove a cached lease run Get-BrokerLease -Uid  | Remove-BrokerLease.4-minTo force an update of cached information and leases on a Delivery Controller run command Update-BrokerLocalLeaseCache. This will delete and recreate the entire cache.5-min

To update specific entries you can run commands such as Update-BrokerLocalLeaseCache -Workers or -Icons.7-minTo disable Connection Leasing run command Set-BrokerSite -ConnectionLeasingEnabled $false. This operation will delete all cached objects from every controller within the site. If you enable Connection Leasing again, lease information will again be cached gradually as users log on and launch resources.6-min

You can use the registry on Delivery Controllers to edit some default settings if you have any reason to do so. Whilst the default settings will not likely ever need changed it is good to know they can be. Some examples below.

To change the sync (local cache) location:

  1. Open RegEdit and navigate to HKLM\Software\Citrix\DesktopServer\ConnectionLeasing.
  2. Create a REG_SZ object with a name of SyncLocation and data value pointing to location that will host the cache.10-min

To change the lease expiration time:

  1. Open RegEdit and navigate to HKLM\Software\Citrix\DesktopServer\ConnectionLeasing.
  2. Create a DWORD object with a name of LeaseExpirationTimeInMins and data value in minutes (default is 20160 = 14 days). This value should be in decimal.11-min

To change the lease data upload to database interval for synchronisation to other Delivery Controllers:

  1. Open RegEdit and navigate to HKLM\Software\Citrix\DesktopServer\ConnectionLeasing.
  2. Create a DWORD object with a name of UploadQueueIdleMaxSecs and data value in seconds (default is 10). This value should be in decimal and dictates how long the upload queue is idle before the lease queue is uploaded to SQL for synchronisation.12-min


When a site enters Connection Leasing mode some event log entries are generated for events such as enumeration and resource launch using Connection Leasing. Below shows the Citrix Broker Service losing connection with the database.13-minThe Broker Service waits for up to 2 minutes to give SQL a bit of time to come back online for example via failover before eventually putting the site in to Leased Connection Mode. 14-minWhen a user logs on to StoreFront, the enumeration files are replayed and StoreFront is able determine which resources the user has access too. There may be multiple events for enumeration. Users are able to launch applications they have used within the past 2 weeks or other applications that are part of the same Delivery Groups of the applications that had been explicitly launched. 15-minWhen a user clicks to launch a resource the lease cache is used to successfully broker that user on to the VDA that last served this same user. 16-minAdditional Notes:

  • Workspace Control (the reconnection of sessions) does not work under Connection Leasing Mode.
  • Leases that have just been cached before a database outage may not have had the time to upload back to the site database to be replicated out to other Delivery Controllers. This results in a scenario where the user will not be able to launch resources.
  • All locally cached data is stored by default in C:\ProgramData\Citrix\Broker\Cache. Subfolders exist and within that more subfolders exist containing XML files. New subdirectories are created automatically to reduce the amount of files that exist in a single directory.
  • Lease information is cached and then synchronised when:
    • Users access their resources.
    • When application details, icons or desktops are changed or updated.
    • When leases expire (by default two weeks since last access).
    • When leasing is disabled or enabled by an administrator.
    • When sessions are long lived (remain active for long periods of time) these sessions are kept updated.
  • When a connection to the Site database is lost there will be a brief (1-2 minutes) amount of downtime to allow for SQL HA environment to fail over before Connection Leasing Mode is enabled.
  • Connection Leasing Mode will only be considered when all Delivery Controllers lose access to the database. If only one Delivery Controller loses connection the VDAs will re-register on to another available database connected Delivery Controller.
  • Sessions may not reconnect for users if an application or desktop launches just before the database connection is lost. In this scenario, a new session is launched for the user.
  • Statically assigned desktops that are powered off before the database becomes unavailable need to be manually powered on before a user who has a cached lease can connect to that machine.
  • Session prelaunch and linger are not available plus any prelaunch/lingering sessions are not ended.

Leave a Reply